Struct Frame 

pub struct Frame { /* private fields */ }

A complete declarative terminal viewport.

Each frame owns a fixed cell grid. Wide graphemes reserve continuation cells, so overwriting either half cannot leave a stale terminal cell behind.

Implementations

impl Frame

pub fn new(size: Size) -> Self

Creates a blank frame using the terminal’s default colors.

Examples found in repository

examples/chat/welcome.rs (line 170)

	pub fn new(charset: Charset) -> Self {
		Self {
			charset,
			frame: Frame::new(Size::new(0, 0)),
			title: fmts!(" {} omp v{} ", charset.icon(Icon::Omp), env!("CARGO_PKG_VERSION")),
			camera: (0.0, 0.0),
			camera_target: (0.0, 0.0),
			last_elapsed: 0.0,
			logo_origin: (0, 0),
			logo: [[None; LOGO_COLS]; LOGO_ROWS],
			logo_at: None,
			backdrop_frame: Frame::new(Size::new(0, 0)),
			backdrop_at: None,
			backdrop: Eclipse::default(),
			surface: Surface::new(),
			pointer: None,
			hover: Tween::settled(0.0),
		}
	}

	/// Records the pointer (0-based cells) for the hover zone and retargets
	/// the camera: the pointer's offset from the logo center maps to camera
	/// lift and a full half-turn of yaw in each direction, matching the
	/// prototype.
	pub fn point_at(&mut self, column: u16, row: u16) {
		self.pointer = Some((column, row));
		self.logo_at = None;
		let center_x = f32::from(self.logo_origin.0) + LOGO_COLS as f32 / 2.0;
		let center_y = f32::from(self.logo_origin.1) + LOGO_ROWS as f32 / 2.0;
		let horizontal = ((f32::from(column) - center_x) / (LOGO_COLS as f32 / 2.0)).clamp(-1.0, 1.0);
		let vertical = ((f32::from(row) - center_y) / (LOGO_ROWS as f32 / 2.0)).clamp(-1.0, 1.0);
		self.camera_target = (-vertical * 0.42, -horizontal * PI);
	}

	/// Paints the card centered in `viewport` at `elapsed` since boot and
	/// returns the full-viewport frame (no stable rows, everything damaged).
	pub fn render(&mut self, viewport: Size, elapsed: Duration) -> &Frame {
		if self.frame.size() != viewport {
			self.frame = Frame::new(viewport);
			self.backdrop_frame = Frame::new(viewport);
			self.backdrop_at = None;
		}
		let clock = elapsed;
		let elapsed = elapsed.as_secs_f32();
		// Exponential pointer chase, frame-rate independent (~100ms lag).
		let delta = (elapsed - self.last_elapsed).max(0.0);
		self.last_elapsed = elapsed;
		let response = 1.0 - (-delta * 10.0).exp();
		self.camera.0 += (self.camera_target.0 - self.camera.0) * response;
		self.camera.1 += (self.camera_target.1 - self.camera.1) * response;
		self.draw_backdrop(viewport, clock, elapsed);

		let logo_interval = ambient_interval(clock, LOGO_IDLE_INTERVAL);
		if self
			.logo_at
			.is_none_or(|rendered_at| clock.saturating_sub(rendered_at) >= logo_interval)
		{
			self.logo = logo_cells(elapsed, self.camera);
			self.logo_at = Some(clock);
		}
		let cols = if viewport.width >= CARD_COLS && viewport.height >= CARD_ROWS {
			Some(CARD_COLS)
		} else if viewport.width >= SMOL_COLS && viewport.height >= CARD_ROWS {
			Some(SMOL_COLS)
		} else {
			None
		};
		let Some(cols) = cols else {
			let left = viewport.width.saturating_sub(LOGO_COLS as u16) / 2;
			let top = viewport.height.saturating_sub(LOGO_ROWS as u16) / 2;
			self.logo_origin = (left, top);
			blit_logo(&mut self.frame, &self.logo, left, top, PLATE);
			return &self.frame;
		};

		let left = (viewport.width - cols) / 2;
		let top = (viewport.height - CARD_ROWS) / 2;
		let hovered = self.pointer.is_some_and(|(x, y)| {
			(left..left + cols).contains(&x) && (top..top + CARD_ROWS).contains(&y)
		});
		self
			.hover
			.retarget(clock, if hovered { 1.0 } else { 0.0 }, HOVER_EASE, Easing::EaseOut);
		let hover = self.hover.sample(clock).clamp(0.0, 1.0);
		self.draw_card(cols, left, top, elapsed, hover);
		&self.frame
	}

examples/chat/demo.rs (line 788)

	pub fn new(ctx: &UiContext) -> Self {
		let editor = Rc::new(RefCell::new({
			let mut editor = Editor::new(EditorOptions::default());
			editor.set_completion(Box::new(SlashCommands::new(demo_commands())));
			editor
		}));
		let edit_outcome = Rc::new(RefCell::new(None));
		let work = Rc::new(RefCell::new(WorkState {
			working: true,
			since:   Duration::ZERO,
			fade:    Tween::settled(GREEN),
		}));
		let model = Rc::new(RefCell::new(Str::new_static("Fable 5++")));
		let pane = EditorPane::new()
			.input(DemoInput::new(Rc::clone(&editor), Rc::clone(&edit_outcome)))
			.status(DemoStatus::new(Rc::clone(&work), Rc::clone(&model), ctx.charset));
		let attachments = pane.attachments();
		let editor_ui = Ui::from_root(pane, 0, ctx.clone());
		Self {
			started_at: Instant::now(),
			ctx: ctx.clone(),
			cancel_hint: ctx.charset.icon(Icon::Cancellable),
			editor_ui,
			editor,
			edit_outcome,
			work,
			last_working: true,
			model,
			attachments,
			transcript: vec![Entry::Command],
			drawn_entries: 0,
			transcript_rows: 0,
			appended_messages: 0,
			emitted_shards: 0,
			last_viewport: Size::new(0, 0),
			height_floor: 0,
			frame: Frame::new(Size::new(0, 0)),
			live_panel: None,
			live_rows: std::array::from_fn(|_| LiveRowCache::new()),
			live_label_scratch: StrMut::with_capacity(40),
			right_inset: 0,
			switch_requested: false,
		}
	}

	/// Routes a key through the editor and reports whether the demo should
	/// exit. Quit policy lives here, not in the editor: once the editor
	/// reports a key unused, `esc` first cancels running work and only quits
	/// at rest; `ctrl-c` always quits.
	pub fn handle_key(&mut self, key: Key) -> bool {
		*self.edit_outcome.borrow_mut() = None;
		let _ = self.editor_ui.handle_key(key);
		let outcome = self
			.edit_outcome
			.borrow_mut()
			.take()
			.unwrap_or(EditOutcome::Ignored);
		match outcome {
			EditOutcome::Submitted(text) => {
				let trimmed = text.trim();
				if trimmed == "/switch" {
					self.switch_requested = true;
					return false;
				}
				if let Some(path) = trimmed
					.strip_prefix("/attach")
					.filter(|rest| rest.is_empty() || rest.starts_with(' '))
				{
					let path = path.trim().to_string();
					if !path.is_empty() {
						self.attach_image(&path);
					}
					return false;
				}
				let _ = self.attachments.take();
				self.refresh_composer();
				self
					.transcript
					.push(Entry::Submitted(Box::new(Submission::new(
						text,
						Self::message_width(self.last_viewport.width),
						&self.ctx,
					))));
				self.set_working(true, self.started_at.elapsed());
				false
			},
			EditOutcome::Changed => {
				self.reconcile_attachments();
				false
			},
			EditOutcome::Ignored => {
				if key == Key::Ctrl('c') {
					return true;
				}
				if key != Key::Esc {
					return false;
				}
				if self.work.borrow().working {
					self.set_working(false, self.started_at.elapsed());
					return false;
				}
				true
			},
		}
	}

	/// Consumes a pending `/switch` request submitted through the composer.
	pub fn take_switch_request(&mut self) -> bool {
		std::mem::take(&mut self.switch_requested)
	}

	/// Routes a document-space mouse report into the editor UI.
	pub fn handle_mouse(&mut self, report: &MouseReport) {
		let editor_height = self.editor_ui.height();
		let editor_y = self.frame.size().height.saturating_sub(editor_height);
		let editor_bottom = editor_y.saturating_add(editor_height);
		if report.row < editor_y || report.row >= editor_bottom {
			return;
		}
		let _ = self
			.editor_ui
			.handle_mouse(report.col, report.row - editor_y, report.kind);
	}

	/// Switches the work state and retargets the brand fade. The status bar
	/// repaints immediately and the fade departs from whatever color is on
	/// screen, so rapid cancel/resume never snaps.
	fn set_working(&mut self, working: bool, now: Duration) {
		{
			let mut work = self.work.borrow_mut();
			if work.working == working {
				return;
			}
			work.working = working;
			work.since = now;
			let target = if working { GREEN } else { MUTED };
			work
				.fade
				.retarget(now, target, BRAND_FADE, Easing::EaseInOut);
		}
		self.editor_ui.invalidate(STATUS_ID);
	}

	/// Reflects a session model switch in the status bar's model segment.
	pub fn set_model(&mut self, name: &str) {
		*self.model.borrow_mut() = Str::from(name);
		self.editor_ui.invalidate(STATUS_ID);
	}

	/// Routes sanitized bracketed paste text through the editor. Dropped
	/// paths to existing image files (quoted, escaped, `file://`, or
	/// multi-file) and any large paste collapse into composer attachment
	/// chips instead of raw text.
	pub fn handle_paste(&mut self, text: &str) {
		let paths = omp_tui::paste::dropped_paths(text);
		if !paths.is_empty()
			&& paths.iter().all(|path| {
				omp_tui::paste::is_image_path(path) && std::path::Path::new(path.as_str()).is_file()
			}) {
			for path in &paths {
				self.attach_image(path);
			}
			return;
		}
		if text.lines().count() > 10 || text.len() > 1000 {
			self.attach_paste(text);
			return;
		}
		let _ = self.editor_ui.handle_paste(text);
	}

	/// Routes Ctrl+Shift+V clipboard text into the composer verbatim: no
	/// attachment staging, no large-paste collapse — the text stays inline
	/// and editable.
	pub fn handle_paste_raw(&mut self, text: &str) {
		let _ = self.editor_ui.handle_paste_raw(text);
	}

	/// Stages `path` on the composer and mentions it in the prompt as an
	/// atomic `<icon> #N` chip expanding to `<ref image=N/>` on submit.
	fn attach_image(&mut self, path: &str) {
		let attachment = self.attachments.push_image(path);
		let payload = format!("<ref image={}/>", attachment.marker);
		self.insert_chip(&attachment, &payload);
	}

	/// Collapses a large paste into a staged attachment card and an atomic
	/// composer chip expanding back to the pasted text on submit.
	fn attach_paste(&mut self, text: &str) {
		let attachment = self.attachments.push_text(text);
		self.insert_chip(&attachment, text);
	}

	/// Inserts one attachment chip as an atomic editor reference.
	fn insert_chip(&mut self, attachment: &Attachment, payload: &str) {
		let chip = chip_label(attachment, self.ctx.charset);
		{
			let mut editor = self.editor.borrow_mut();
			let _ = editor.insert_reference(&chip, payload);
			let _ = editor.insert_text(" ");
		}
		self.refresh_composer();
	}

	/// Hides staged attachments whose chip the user deleted from the
	/// composer (and re-shows them after an undo). Presence is derived
	/// from the buffer's atomic ranges, never from text matching.
	fn reconcile_attachments(&mut self) {
		let charset = self.ctx.charset;
		let changed = {
			let editor = self.editor.borrow();
			let text = editor.text();
			let ranges = editor.atom_ranges();
			self.attachments.set_visible(|attachment| {
				let chip = chip_label(attachment, charset);
				ranges
					.iter()
					.any(|&(start, end)| text.get(start..end) == Some(chip.as_str()))
			})
		};
		if changed {
			self.refresh_composer();
		}
	}

	/// Relayouts the composer after out-of-band state changed its height.
	fn refresh_composer(&mut self) {
		let width = self.editor_ui.frame().size().width;
		if width > 0 {
			self.editor_ui.resize(width);
		}
	}

	/// Reserves `cols` at the right edge for a composited rail, so the
	/// composer's right-docked chrome stays visible beside it. The next
	/// render relayouts the editor at the narrowed width.
	pub const fn set_right_inset(&mut self, cols: u16) {
		self.right_inset = cols;
	}

	/// The width the composer may actually occupy at `viewport`.
	fn composer_width(&self, viewport: Size) -> u16 {
		viewport.width.saturating_sub(self.right_inset).max(1)
	}

	/// Updates the retained logical document and reports its repainted rows.
	pub fn render(&mut self, viewport: Size) -> RenderedFrame<'_> {
		self.render_at(viewport, self.started_at.elapsed())
	}

	fn render_at(&mut self, viewport: Size, elapsed: Duration) -> RenderedFrame<'_> {
		if viewport.width == 0 || viewport.height == 0 {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			self.live_panel = None;
			self.frame = Frame::new(viewport);
			return RenderedFrame {
				frame:       &self.frame,
				stable_rows: 0,
				damage:      SmallVec::new(),
			};
		}
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		// Fires due animation wakes (the status bar's spinner and brand
		// fade) so the blit below picks up fresh retained pixels.
		self.editor_ui.tick(elapsed);
		let editor_changed = self.editor_ui.take_frame_damage();

		// A viewport change starts a fresh renderer session: replay the
		// whole transcript log at the new width. Between rebuilds the log
		// is append-only and every drawn row is final, so selections over
		// transcript text stay anchored to it in every terminal.
		let rebuild = self.last_viewport != viewport;
		if rebuild {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			let message_width = Self::message_width(viewport.width);
			for entry in &mut self.transcript {
				if let Entry::Submitted(submission) = entry {
					submission.resize(message_width, &self.ctx);
				}
			}
		}
		while self.appended_messages < Self::visible_messages(elapsed) {
			self.transcript.push(Entry::Message(self.appended_messages));
			self.appended_messages += 1;
		}
		while self.emitted_shards < Self::finished_shards(elapsed) {
			self.emitted_shards += 1;
			self.transcript.push(Entry::ShardDone(self.emitted_shards));
		}

		let mut new_rows = 0_u16;
		for entry in &self.transcript[self.drawn_entries..] {
			new_rows = new_rows.saturating_add(Self::entry_height(entry, viewport.width, &self.ctx));
		}
		let transcript_rows = self.transcript_rows.saturating_add(new_rows);
		let editor_height = self.editor_ui.height();
		// Native scrollback is append-only, so the logical document may
		// never shrink while the seam is live: band rows that close again
		// (extra input lines) become blank padding that heals as the
		// transcript grows.
		let natural_height = transcript_rows.saturating_add(Self::band_height(editor_height));
		self.height_floor = self.height_floor.max(natural_height);
		let document_height = self.height_floor.max(viewport.height);
		let transcript_damage_start = if rebuild { 0 } else { self.transcript_rows };
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_y = document_height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		let panel = Rect::new(margin, panel_y, content_width, panel_height);
		let repaint_suffix = rebuild || new_rows > 0 || self.live_panel != Some(panel);
		if rebuild {
			self.frame = Frame::new(Size::new(viewport.width, document_height));
		} else {
			self.frame.resize_height(document_height, base_style());
		}
		if repaint_suffix {
			self.frame.fill(
				Rect::new(
					0,
					transcript_damage_start,
					viewport.width,
					document_height.saturating_sub(transcript_damage_start),
				),
				base_style(),
			);
		}

		// Paint the new transcript entries; rows above `transcript_rows`
		// are final and never repainted.
		let mut y = self.transcript_rows;
		for index in self.drawn_entries..self.transcript.len() {
			let used = self.draw_entry_at(index, y, viewport.width);
			y = y.saturating_add(used);
		}
		self.drawn_entries = self.transcript.len();
		self.transcript_rows = y;

		// The live band repaints in place at the bottom of the document.
		let animation_frame = Self::animation_frame(elapsed);
		let panel_changed = draw_live_panel(
			&mut self.frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			panel,
			repaint_suffix,
			self.emitted_shards,
			animation_frame,
			self.ctx.charset,
		);
		let working = self.work.borrow().working;
		let working_changed = self.last_working != working;
		if !repaint_suffix && self.last_working && !working {
			self
				.frame
				.fill(Rect::new(0, working_y, viewport.width, 1), base_style());
		}
		if working {
			Self::draw_working(&mut self.frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut self.frame, title_y, self.right_inset);
		if repaint_suffix || editor_changed {
			self
				.frame
				.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);
		}
		let mut damage = SmallVec::new();
		if repaint_suffix {
			damage.push((transcript_damage_start, document_height));
		} else {
			if panel_changed {
				damage.push((panel_y, panel_y.saturating_add(panel_height)));
			}
			if working || working_changed {
				damage.push((working_y, working_y.saturating_add(1)));
			}
			if editor_changed {
				damage.push((editor_y, document_height));
			}
		}
		self.last_working = working;
		self.live_panel = Some(panel);

		RenderedFrame { frame: &self.frame, stable_rows: self.transcript_rows, damage }
	}

	fn generation(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / EMIT_INTERVAL.as_millis()).unwrap_or(u64::MAX)
	}

	fn animation_frame(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / 80).unwrap_or(u64::MAX)
	}

	fn visible_messages(elapsed: Duration) -> usize {
		let interval = MESSAGE_INTERVAL.as_millis();
		usize::try_from(elapsed.as_millis() / interval + 1)
			.unwrap_or(usize::MAX)
			.min(4)
	}

	/// Shards whose permanent result line has been appended by `elapsed`:
	/// two per emit tick, capped well inside `u16` document heights.
	fn finished_shards(elapsed: Duration) -> u16 {
		u16::try_from(Self::generation(elapsed).saturating_mul(2).min(60_000))
			.expect("finished shard count is clamped")
	}

	/// Rows the bottom live band occupies: the shard panel, a blank
	/// separator, the activity row, the title air row, and the editor
	/// block.
	const fn band_height(editor_height: u16) -> u16 {
		LIVE_SHARD_ROWS + 2 + 3 + editor_height
	}

	/// Rows `entry` will occupy at `width`, including its trailing blank.
	fn entry_height(entry: &Entry, width: u16, ctx: &UiContext) -> u16 {
		match entry {
			Entry::Command => 5,
			Entry::Message(message) => {
				let mut scratch = Frame::new(Size::new(width, 48));
				Self::draw_message(&mut scratch, 0, *message, width, ctx.charset)
			},
			Entry::ShardDone(_) => 1,
			Entry::Submitted(submission) => submission.height().saturating_add(1),
		}
	}

	const fn message_width(width: u16) -> u16 {
		let narrowed = width.saturating_sub(3);
		if narrowed == 0 { 1 } else { narrowed }
	}

	/// Paints one transcript entry at `y` and returns the rows it used.
	fn draw_entry_at(&mut self, index: usize, y: u16, width: u16) -> u16 {
		Self::draw_entry(&mut self.frame, &self.transcript[index], y, width, &self.ctx)
	}

	/// Paints `entry` into any frame at `y` and returns the rows it used,
	/// including the trailing blank.
	fn draw_entry(frame: &mut Frame, entry: &Entry, y: u16, width: u16, ctx: &UiContext) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		match entry {
			Entry::Command => {
				draw_command_box(frame, Rect::new(margin, y, content_width, 4), ctx.charset);
				5
			},
			Entry::Message(message) => Self::draw_message(frame, y, *message, width, ctx.charset),
			Entry::ShardDone(shard) => {
				Self::draw_shard_done(frame, y, *shard, width, ctx.charset);
				1
			},
			Entry::Submitted(submission) => {
				draw_submission(frame, y, submission, ctx.charset);
				submission.height().saturating_add(1)
			},
		}
	}

	/// Composes exactly one viewport of throwaway resize-drag content at the
	/// new geometry: the live band anchors to the bottom, then transcript
	/// entries are walked backward and rewrapped at `viewport.width` until
	/// the screen is full — O(viewport) work per drag frame, with the
	/// topmost entry sliced when it only partially fits. Retained transcript
	/// state is untouched, so the settle rebuild replays full history
	/// exactly once.
	pub fn render_resize_preview(&mut self, viewport: Size) -> Frame {
		let elapsed = self.started_at.elapsed();
		let mut frame = Frame::new(viewport);
		if viewport.width == 0 || viewport.height == 0 {
			return frame;
		}
		frame.fill(Rect::new(0, 0, viewport.width, viewport.height), base_style());
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		self.editor_ui.tick(elapsed);

		// The live band, laid out exactly like the retained document's.
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_height = self.editor_ui.height();
		let editor_y = viewport.height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		draw_live_panel(
			&mut frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			Rect::new(margin, panel_y, content_width, panel_height),
			true,
			self.emitted_shards,
			Self::animation_frame(elapsed),
			self.ctx.charset,
		);
		if self.work.borrow().working {
			Self::draw_working(&mut frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut frame, title_y, self.right_inset);
		frame.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);

		// Transcript tail, bottom-up above the band.
		let mut remaining = panel_y;
		for entry in self.transcript.iter().rev() {
			if remaining == 0 {
				break;
			}
			let height = Self::entry_height(entry, viewport.width, &self.ctx);
			if height == 0 {
				continue;
			}
			if height <= remaining {
				remaining -= height;
				Self::draw_entry(&mut frame, entry, remaining, viewport.width, &self.ctx);
			} else {
				// Slice the bottom rows of the partially visible entry.
				let mut scratch = Frame::new(Size::new(viewport.width, height));
				scratch.fill(Rect::new(0, 0, viewport.width, height), base_style());
				Self::draw_entry(&mut scratch, entry, 0, viewport.width, &self.ctx);
				frame.blit(&scratch, height - remaining, remaining, 0, 0);
				remaining = 0;
			}
		}
		frame
	}

examples/footers.rs (line 117)

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

/// Per-frame paint inputs shared by every study.
struct Scene {
	charset: Charset,
	width:   u16,
	elapsed: Duration,
}

impl Scene {
	const fn spinner(&self) -> &'static str {
		self.charset.spinner().at(self.elapsed)
	}

	fn timer(&self) -> Str {
		let seconds = self.elapsed.as_secs();
		if seconds < 60 {
			fmts!("{seconds}s")
		} else {
			fmts!("{}m", seconds / 60)
		}
	}

	const fn right_edge(&self) -> u16 {
		self.width.saturating_sub(1)
	}
}

/// One study: a header line and a `rows`-tall live mock beneath it.
struct Study {
	title: &'static str,
	note:  &'static str,
	rows:  u16,
	draw:  fn(&mut Frame, u16, &Scene),
}

const STUDIES: [Study; 6] = [
	Study {
		title: "pi parity",
		note:  "border carries the band left and the title right; the intent rides its own spinner \
		        row",
		rows:  4,
		draw:  study_pi_parity,
	},
	Study {
		title: "gap title",
		note:  "the air row earns its keep — session title idles right-aligned in the gap",
		rows:  4,
		draw:  study_gap_title,
	},
	Study {
		title: "band title",
		note:  "title as the left band's second segment; session facts dock right",
		rows:  4,
		draw:  study_band_title,
	},
	Study {
		title: "prompt title",
		note:  "split + air untouched; the title rests on the prompt row and yields while typing",
		rows:  4,
		draw:  study_prompt_title,
	},
	Study {
		title: "crown",
		note:  "title crowns the whole block; narration, gap, and split bands breathe below it",
		rows:  5,
		draw:  study_crown,
	},
	Study {
		title: "hem",
		note:  "title stitched into the top border, band into the bottom hem",
		rows:  4,
		draw:  study_hem,
	},
];

/// Renders the full document — title block plus every study — at width.
fn compose(scene: &Scene) -> Frame {
	let height = STUDIES
		.iter()
		.map(|study| study.rows + 3)
		.fold(3_u16, u16::saturating_add);
	let mut frame = Frame::new(Size::new(scene.width, height));
	frame.fill(Rect::new(0, 0, scene.width, height), ink(TEXT));

	let column = frame.put(1, 0, "composer footer studies", ink(TEXT).bold());
	frame.put(
		column.saturating_add(2),
		0,
		"split + air gap, six session-title placements",
		ink(MUTED),
	);
	frame.put(1, 1, "↑/↓ scroll · PgUp/PgDn page · Home/End jump · q quits", ink(FAINT));

	let mut y = 3_u16;
	for (index, study) in STUDIES.iter().enumerate() {
		let number = fmts!("{:>2} ", index + 1);
		let mut column = frame.put(1, y, &number, ink(GOLD).bold());
		column = frame.put(column, y, study.title, ink(TEXT).bold());
		column = frame.put(column, y, "  ", ink(FAINT));
		frame.put(column, y, study.note, ink(MUTED));
		(study.draw)(&mut frame, y + 1, scene);
		y = y.saturating_add(study.rows + 3);
	}
	frame
}

pub fn resize_height(&mut self, height: u16, style: Style)

Changes the document height, preserving retained rows and filling growth with styled blanks.

Examples found in repository

examples/chat/demo.rs (line 1077)

	fn render_at(&mut self, viewport: Size, elapsed: Duration) -> RenderedFrame<'_> {
		if viewport.width == 0 || viewport.height == 0 {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			self.live_panel = None;
			self.frame = Frame::new(viewport);
			return RenderedFrame {
				frame:       &self.frame,
				stable_rows: 0,
				damage:      SmallVec::new(),
			};
		}
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		// Fires due animation wakes (the status bar's spinner and brand
		// fade) so the blit below picks up fresh retained pixels.
		self.editor_ui.tick(elapsed);
		let editor_changed = self.editor_ui.take_frame_damage();

		// A viewport change starts a fresh renderer session: replay the
		// whole transcript log at the new width. Between rebuilds the log
		// is append-only and every drawn row is final, so selections over
		// transcript text stay anchored to it in every terminal.
		let rebuild = self.last_viewport != viewport;
		if rebuild {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			let message_width = Self::message_width(viewport.width);
			for entry in &mut self.transcript {
				if let Entry::Submitted(submission) = entry {
					submission.resize(message_width, &self.ctx);
				}
			}
		}
		while self.appended_messages < Self::visible_messages(elapsed) {
			self.transcript.push(Entry::Message(self.appended_messages));
			self.appended_messages += 1;
		}
		while self.emitted_shards < Self::finished_shards(elapsed) {
			self.emitted_shards += 1;
			self.transcript.push(Entry::ShardDone(self.emitted_shards));
		}

		let mut new_rows = 0_u16;
		for entry in &self.transcript[self.drawn_entries..] {
			new_rows = new_rows.saturating_add(Self::entry_height(entry, viewport.width, &self.ctx));
		}
		let transcript_rows = self.transcript_rows.saturating_add(new_rows);
		let editor_height = self.editor_ui.height();
		// Native scrollback is append-only, so the logical document may
		// never shrink while the seam is live: band rows that close again
		// (extra input lines) become blank padding that heals as the
		// transcript grows.
		let natural_height = transcript_rows.saturating_add(Self::band_height(editor_height));
		self.height_floor = self.height_floor.max(natural_height);
		let document_height = self.height_floor.max(viewport.height);
		let transcript_damage_start = if rebuild { 0 } else { self.transcript_rows };
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_y = document_height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		let panel = Rect::new(margin, panel_y, content_width, panel_height);
		let repaint_suffix = rebuild || new_rows > 0 || self.live_panel != Some(panel);
		if rebuild {
			self.frame = Frame::new(Size::new(viewport.width, document_height));
		} else {
			self.frame.resize_height(document_height, base_style());
		}
		if repaint_suffix {
			self.frame.fill(
				Rect::new(
					0,
					transcript_damage_start,
					viewport.width,
					document_height.saturating_sub(transcript_damage_start),
				),
				base_style(),
			);
		}

		// Paint the new transcript entries; rows above `transcript_rows`
		// are final and never repainted.
		let mut y = self.transcript_rows;
		for index in self.drawn_entries..self.transcript.len() {
			let used = self.draw_entry_at(index, y, viewport.width);
			y = y.saturating_add(used);
		}
		self.drawn_entries = self.transcript.len();
		self.transcript_rows = y;

		// The live band repaints in place at the bottom of the document.
		let animation_frame = Self::animation_frame(elapsed);
		let panel_changed = draw_live_panel(
			&mut self.frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			panel,
			repaint_suffix,
			self.emitted_shards,
			animation_frame,
			self.ctx.charset,
		);
		let working = self.work.borrow().working;
		let working_changed = self.last_working != working;
		if !repaint_suffix && self.last_working && !working {
			self
				.frame
				.fill(Rect::new(0, working_y, viewport.width, 1), base_style());
		}
		if working {
			Self::draw_working(&mut self.frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut self.frame, title_y, self.right_inset);
		if repaint_suffix || editor_changed {
			self
				.frame
				.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);
		}
		let mut damage = SmallVec::new();
		if repaint_suffix {
			damage.push((transcript_damage_start, document_height));
		} else {
			if panel_changed {
				damage.push((panel_y, panel_y.saturating_add(panel_height)));
			}
			if working || working_changed {
				damage.push((working_y, working_y.saturating_add(1)));
			}
			if editor_changed {
				damage.push((editor_y, document_height));
			}
		}
		self.last_working = working;
		self.live_panel = Some(panel);

		RenderedFrame { frame: &self.frame, stable_rows: self.transcript_rows, damage }
	}

pub fn set_soft_wrap(&mut self, y: u16)

Flags row y as soft-wrapping onto row y + 1: the pair renders as one logical line broken mid-word only by the frame width. The renderer may join the boundary with terminal autowrap so native selection copies it unbroken, provided the row’s content truly reaches the final column.

Ignored unless both rows exist. Cleared by Frame::clear, Frame::resize_height shrinkage, and every rebuild — the flag is layout metadata, not cell content.

Examples found in repository

examples/chat/demo.rs (line 1721)

fn draw_flowed(frame: &mut Frame, rect: Rect, spans: &[Span<'_>]) -> u16 {
	if rect.width == 0 || rect.height == 0 {
		return 0;
	}
	let full_row = rect.x == 0 && rect.width == frame.size().width;
	let mut row = 0_u16;
	let mut column = 0_u16;
	let mut drew_anything = false;

	for span in spans {
		for grapheme in xutf::graphemes_str(span.text) {
			let grapheme_width = visible_width(grapheme);
			if grapheme_width == 0 || grapheme_width > rect.width {
				continue;
			}
			if column.saturating_add(grapheme_width) > rect.width {
				// Only an exactly-filled row is byte-joinable by autowrap.
				if full_row && column == rect.width {
					frame.set_soft_wrap(rect.y.saturating_add(row));
				}
				row += 1;
				column = 0;
			}
			if row >= rect.height {
				return rect.height;
			}
			frame.put(rect.x + column, rect.y + row, grapheme, span.style);
			column += grapheme_width;
			drew_anything = true;
		}
	}

	if drew_anything { row + 1 } else { 0 }
}

pub fn soft_wrap(&self, y: u16) -> bool

Whether row y was flagged as soft-wrapping onto row y + 1.

pub const fn size(&self) -> Size

Returns the frame dimensions.

Examples found in repository

examples/chat/demo.rs (line 866)

	pub fn handle_mouse(&mut self, report: &MouseReport) {
		let editor_height = self.editor_ui.height();
		let editor_y = self.frame.size().height.saturating_sub(editor_height);
		let editor_bottom = editor_y.saturating_add(editor_height);
		if report.row < editor_y || report.row >= editor_bottom {
			return;
		}
		let _ = self
			.editor_ui
			.handle_mouse(report.col, report.row - editor_y, report.kind);
	}

	/// Switches the work state and retargets the brand fade. The status bar
	/// repaints immediately and the fade departs from whatever color is on
	/// screen, so rapid cancel/resume never snaps.
	fn set_working(&mut self, working: bool, now: Duration) {
		{
			let mut work = self.work.borrow_mut();
			if work.working == working {
				return;
			}
			work.working = working;
			work.since = now;
			let target = if working { GREEN } else { MUTED };
			work
				.fade
				.retarget(now, target, BRAND_FADE, Easing::EaseInOut);
		}
		self.editor_ui.invalidate(STATUS_ID);
	}

	/// Reflects a session model switch in the status bar's model segment.
	pub fn set_model(&mut self, name: &str) {
		*self.model.borrow_mut() = Str::from(name);
		self.editor_ui.invalidate(STATUS_ID);
	}

	/// Routes sanitized bracketed paste text through the editor. Dropped
	/// paths to existing image files (quoted, escaped, `file://`, or
	/// multi-file) and any large paste collapse into composer attachment
	/// chips instead of raw text.
	pub fn handle_paste(&mut self, text: &str) {
		let paths = omp_tui::paste::dropped_paths(text);
		if !paths.is_empty()
			&& paths.iter().all(|path| {
				omp_tui::paste::is_image_path(path) && std::path::Path::new(path.as_str()).is_file()
			}) {
			for path in &paths {
				self.attach_image(path);
			}
			return;
		}
		if text.lines().count() > 10 || text.len() > 1000 {
			self.attach_paste(text);
			return;
		}
		let _ = self.editor_ui.handle_paste(text);
	}

	/// Routes Ctrl+Shift+V clipboard text into the composer verbatim: no
	/// attachment staging, no large-paste collapse — the text stays inline
	/// and editable.
	pub fn handle_paste_raw(&mut self, text: &str) {
		let _ = self.editor_ui.handle_paste_raw(text);
	}

	/// Stages `path` on the composer and mentions it in the prompt as an
	/// atomic `<icon> #N` chip expanding to `<ref image=N/>` on submit.
	fn attach_image(&mut self, path: &str) {
		let attachment = self.attachments.push_image(path);
		let payload = format!("<ref image={}/>", attachment.marker);
		self.insert_chip(&attachment, &payload);
	}

	/// Collapses a large paste into a staged attachment card and an atomic
	/// composer chip expanding back to the pasted text on submit.
	fn attach_paste(&mut self, text: &str) {
		let attachment = self.attachments.push_text(text);
		self.insert_chip(&attachment, text);
	}

	/// Inserts one attachment chip as an atomic editor reference.
	fn insert_chip(&mut self, attachment: &Attachment, payload: &str) {
		let chip = chip_label(attachment, self.ctx.charset);
		{
			let mut editor = self.editor.borrow_mut();
			let _ = editor.insert_reference(&chip, payload);
			let _ = editor.insert_text(" ");
		}
		self.refresh_composer();
	}

	/// Hides staged attachments whose chip the user deleted from the
	/// composer (and re-shows them after an undo). Presence is derived
	/// from the buffer's atomic ranges, never from text matching.
	fn reconcile_attachments(&mut self) {
		let charset = self.ctx.charset;
		let changed = {
			let editor = self.editor.borrow();
			let text = editor.text();
			let ranges = editor.atom_ranges();
			self.attachments.set_visible(|attachment| {
				let chip = chip_label(attachment, charset);
				ranges
					.iter()
					.any(|&(start, end)| text.get(start..end) == Some(chip.as_str()))
			})
		};
		if changed {
			self.refresh_composer();
		}
	}

	/// Relayouts the composer after out-of-band state changed its height.
	fn refresh_composer(&mut self) {
		let width = self.editor_ui.frame().size().width;
		if width > 0 {
			self.editor_ui.resize(width);
		}
	}

	/// Reserves `cols` at the right edge for a composited rail, so the
	/// composer's right-docked chrome stays visible beside it. The next
	/// render relayouts the editor at the narrowed width.
	pub const fn set_right_inset(&mut self, cols: u16) {
		self.right_inset = cols;
	}

	/// The width the composer may actually occupy at `viewport`.
	fn composer_width(&self, viewport: Size) -> u16 {
		viewport.width.saturating_sub(self.right_inset).max(1)
	}

	/// Updates the retained logical document and reports its repainted rows.
	pub fn render(&mut self, viewport: Size) -> RenderedFrame<'_> {
		self.render_at(viewport, self.started_at.elapsed())
	}

	fn render_at(&mut self, viewport: Size, elapsed: Duration) -> RenderedFrame<'_> {
		if viewport.width == 0 || viewport.height == 0 {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			self.live_panel = None;
			self.frame = Frame::new(viewport);
			return RenderedFrame {
				frame:       &self.frame,
				stable_rows: 0,
				damage:      SmallVec::new(),
			};
		}
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		// Fires due animation wakes (the status bar's spinner and brand
		// fade) so the blit below picks up fresh retained pixels.
		self.editor_ui.tick(elapsed);
		let editor_changed = self.editor_ui.take_frame_damage();

		// A viewport change starts a fresh renderer session: replay the
		// whole transcript log at the new width. Between rebuilds the log
		// is append-only and every drawn row is final, so selections over
		// transcript text stay anchored to it in every terminal.
		let rebuild = self.last_viewport != viewport;
		if rebuild {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			let message_width = Self::message_width(viewport.width);
			for entry in &mut self.transcript {
				if let Entry::Submitted(submission) = entry {
					submission.resize(message_width, &self.ctx);
				}
			}
		}
		while self.appended_messages < Self::visible_messages(elapsed) {
			self.transcript.push(Entry::Message(self.appended_messages));
			self.appended_messages += 1;
		}
		while self.emitted_shards < Self::finished_shards(elapsed) {
			self.emitted_shards += 1;
			self.transcript.push(Entry::ShardDone(self.emitted_shards));
		}

		let mut new_rows = 0_u16;
		for entry in &self.transcript[self.drawn_entries..] {
			new_rows = new_rows.saturating_add(Self::entry_height(entry, viewport.width, &self.ctx));
		}
		let transcript_rows = self.transcript_rows.saturating_add(new_rows);
		let editor_height = self.editor_ui.height();
		// Native scrollback is append-only, so the logical document may
		// never shrink while the seam is live: band rows that close again
		// (extra input lines) become blank padding that heals as the
		// transcript grows.
		let natural_height = transcript_rows.saturating_add(Self::band_height(editor_height));
		self.height_floor = self.height_floor.max(natural_height);
		let document_height = self.height_floor.max(viewport.height);
		let transcript_damage_start = if rebuild { 0 } else { self.transcript_rows };
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_y = document_height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		let panel = Rect::new(margin, panel_y, content_width, panel_height);
		let repaint_suffix = rebuild || new_rows > 0 || self.live_panel != Some(panel);
		if rebuild {
			self.frame = Frame::new(Size::new(viewport.width, document_height));
		} else {
			self.frame.resize_height(document_height, base_style());
		}
		if repaint_suffix {
			self.frame.fill(
				Rect::new(
					0,
					transcript_damage_start,
					viewport.width,
					document_height.saturating_sub(transcript_damage_start),
				),
				base_style(),
			);
		}

		// Paint the new transcript entries; rows above `transcript_rows`
		// are final and never repainted.
		let mut y = self.transcript_rows;
		for index in self.drawn_entries..self.transcript.len() {
			let used = self.draw_entry_at(index, y, viewport.width);
			y = y.saturating_add(used);
		}
		self.drawn_entries = self.transcript.len();
		self.transcript_rows = y;

		// The live band repaints in place at the bottom of the document.
		let animation_frame = Self::animation_frame(elapsed);
		let panel_changed = draw_live_panel(
			&mut self.frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			panel,
			repaint_suffix,
			self.emitted_shards,
			animation_frame,
			self.ctx.charset,
		);
		let working = self.work.borrow().working;
		let working_changed = self.last_working != working;
		if !repaint_suffix && self.last_working && !working {
			self
				.frame
				.fill(Rect::new(0, working_y, viewport.width, 1), base_style());
		}
		if working {
			Self::draw_working(&mut self.frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut self.frame, title_y, self.right_inset);
		if repaint_suffix || editor_changed {
			self
				.frame
				.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);
		}
		let mut damage = SmallVec::new();
		if repaint_suffix {
			damage.push((transcript_damage_start, document_height));
		} else {
			if panel_changed {
				damage.push((panel_y, panel_y.saturating_add(panel_height)));
			}
			if working || working_changed {
				damage.push((working_y, working_y.saturating_add(1)));
			}
			if editor_changed {
				damage.push((editor_y, document_height));
			}
		}
		self.last_working = working;
		self.live_panel = Some(panel);

		RenderedFrame { frame: &self.frame, stable_rows: self.transcript_rows, damage }
	}

	fn generation(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / EMIT_INTERVAL.as_millis()).unwrap_or(u64::MAX)
	}

	fn animation_frame(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / 80).unwrap_or(u64::MAX)
	}

	fn visible_messages(elapsed: Duration) -> usize {
		let interval = MESSAGE_INTERVAL.as_millis();
		usize::try_from(elapsed.as_millis() / interval + 1)
			.unwrap_or(usize::MAX)
			.min(4)
	}

	/// Shards whose permanent result line has been appended by `elapsed`:
	/// two per emit tick, capped well inside `u16` document heights.
	fn finished_shards(elapsed: Duration) -> u16 {
		u16::try_from(Self::generation(elapsed).saturating_mul(2).min(60_000))
			.expect("finished shard count is clamped")
	}

	/// Rows the bottom live band occupies: the shard panel, a blank
	/// separator, the activity row, the title air row, and the editor
	/// block.
	const fn band_height(editor_height: u16) -> u16 {
		LIVE_SHARD_ROWS + 2 + 3 + editor_height
	}

	/// Rows `entry` will occupy at `width`, including its trailing blank.
	fn entry_height(entry: &Entry, width: u16, ctx: &UiContext) -> u16 {
		match entry {
			Entry::Command => 5,
			Entry::Message(message) => {
				let mut scratch = Frame::new(Size::new(width, 48));
				Self::draw_message(&mut scratch, 0, *message, width, ctx.charset)
			},
			Entry::ShardDone(_) => 1,
			Entry::Submitted(submission) => submission.height().saturating_add(1),
		}
	}

	const fn message_width(width: u16) -> u16 {
		let narrowed = width.saturating_sub(3);
		if narrowed == 0 { 1 } else { narrowed }
	}

	/// Paints one transcript entry at `y` and returns the rows it used.
	fn draw_entry_at(&mut self, index: usize, y: u16, width: u16) -> u16 {
		Self::draw_entry(&mut self.frame, &self.transcript[index], y, width, &self.ctx)
	}

	/// Paints `entry` into any frame at `y` and returns the rows it used,
	/// including the trailing blank.
	fn draw_entry(frame: &mut Frame, entry: &Entry, y: u16, width: u16, ctx: &UiContext) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		match entry {
			Entry::Command => {
				draw_command_box(frame, Rect::new(margin, y, content_width, 4), ctx.charset);
				5
			},
			Entry::Message(message) => Self::draw_message(frame, y, *message, width, ctx.charset),
			Entry::ShardDone(shard) => {
				Self::draw_shard_done(frame, y, *shard, width, ctx.charset);
				1
			},
			Entry::Submitted(submission) => {
				draw_submission(frame, y, submission, ctx.charset);
				submission.height().saturating_add(1)
			},
		}
	}

	/// Composes exactly one viewport of throwaway resize-drag content at the
	/// new geometry: the live band anchors to the bottom, then transcript
	/// entries are walked backward and rewrapped at `viewport.width` until
	/// the screen is full — O(viewport) work per drag frame, with the
	/// topmost entry sliced when it only partially fits. Retained transcript
	/// state is untouched, so the settle rebuild replays full history
	/// exactly once.
	pub fn render_resize_preview(&mut self, viewport: Size) -> Frame {
		let elapsed = self.started_at.elapsed();
		let mut frame = Frame::new(viewport);
		if viewport.width == 0 || viewport.height == 0 {
			return frame;
		}
		frame.fill(Rect::new(0, 0, viewport.width, viewport.height), base_style());
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		self.editor_ui.tick(elapsed);

		// The live band, laid out exactly like the retained document's.
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_height = self.editor_ui.height();
		let editor_y = viewport.height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		draw_live_panel(
			&mut frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			Rect::new(margin, panel_y, content_width, panel_height),
			true,
			self.emitted_shards,
			Self::animation_frame(elapsed),
			self.ctx.charset,
		);
		if self.work.borrow().working {
			Self::draw_working(&mut frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut frame, title_y, self.right_inset);
		frame.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);

		// Transcript tail, bottom-up above the band.
		let mut remaining = panel_y;
		for entry in self.transcript.iter().rev() {
			if remaining == 0 {
				break;
			}
			let height = Self::entry_height(entry, viewport.width, &self.ctx);
			if height == 0 {
				continue;
			}
			if height <= remaining {
				remaining -= height;
				Self::draw_entry(&mut frame, entry, remaining, viewport.width, &self.ctx);
			} else {
				// Slice the bottom rows of the partially visible entry.
				let mut scratch = Frame::new(Size::new(viewport.width, height));
				scratch.fill(Rect::new(0, 0, viewport.width, height), base_style());
				Self::draw_entry(&mut scratch, entry, 0, viewport.width, &self.ctx);
				frame.blit(&scratch, height - remaining, remaining, 0, 0);
				remaining = 0;
			}
		}
		frame
	}

	/// Paints the n-th scripted message and returns rows used including
	/// the trailing blank. Measurement draws into a scratch frame.
	fn draw_message(frame: &mut Frame, y: u16, message: usize, width: u16, charset: Charset) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		if message == 2 {
			draw_edit_box(frame, Rect::new(margin, y, content_width, EDIT_BOX_HEIGHT), charset);
			return EDIT_BOX_HEIGHT + 1;
		}
		let bottom = frame.size().height;
		let spans = Self::message_spans(message);
		// Prose flows edge-to-edge grapheme-exact — no side pads — so every
		// wrapped row re-joins byte-for-byte in native selection.
		let used = draw_flowed(frame, Rect::new(0, y, width, bottom.saturating_sub(y)), &spans);
		used.saturating_add(1)
	}

	fn message_spans(message: usize) -> SmallVec<Span<'static>, 3> {
		let mut spans = SmallVec::new();
		match message {
			0 => {
				spans.push(Span::new("Transcript rows are ", prose_style()));
				spans.push(Span::new("append-only", code_style()));
				spans.push(Span::new(
					": every line is painted once, becomes stable, and rides into native scrollback \
					 with any selection anchored to it.",
					prose_style(),
				));
			},
			1 => {
				spans.push(Span::new(
					"Only the bottom band repaints in place — the live shard panel, the activity \
					 shimmer, and the composer. Rows above it are never rewritten.",
					prose_style(),
				));
			},
			_ => {
				spans.push(Span::new(
					"On terminals that move margin-scrolled rows into scrollback, commits scroll only \
					 the stable transcript through a ",
					prose_style(),
				));
				spans.push(Span::new("DECSTBM top region", code_style()));
				spans.push(Span::new(", so the live band never shifts on screen.", prose_style()));
			},
		}
		spans
	}

	/// Appends a finished shard's permanent one-line result.
	fn draw_shard_done(frame: &mut Frame, y: u16, shard: u16, width: u16, charset: Charset) {
		let margin = u16::from(width >= 50);
		let prefix = fmts!(" {} shard {shard:03} passed", charset.check());
		let detail = fmts!("  workspace-{shard:03}.test.ts  [100%]");
		draw_line(frame, margin + 1, y, width.saturating_sub(margin * 2).saturating_sub(2), &[
			Span::new(prefix.as_str(), ink(GREEN)),
			Span::new(detail.as_str(), ink(MUTED)),
		]);
	}

	/// Shimmering activity line above the editor. The spinner and timer
	/// live in the status bar's brand segment; this row only narrates.
	fn draw_working(frame: &mut Frame, y: u16, elapsed: Duration, hint: &str) {
		if y >= frame.size().height || frame.size().width < 4 {
			return;
		}
		let start = u16::from(frame.size().width >= 50);
		let mut column = start;
		let length = xutf::graphemes_str(WORKING_MESSAGE)
			.count()
			.saturating_add(xutf::graphemes_str(hint).count())
			.saturating_add(1);
		let length = u16::try_from(length).unwrap_or(u16::MAX);
		let shimmer = Shimmer::new(elapsed, SHIMMER_PERIOD, length);
		let right = frame.size().width.saturating_sub(1);
		draw_shimmer(frame, &mut column, start, y, right, hint, shimmer, ink(CYAN));
		draw_shimmer(frame, &mut column, start, y, right, " ", shimmer, ink(GREEN));
		draw_shimmer(frame, &mut column, start, y, right, WORKING_MESSAGE, shimmer, ink(GREEN));
	}

	/// The session title resting right-aligned in the air row between
	/// the working narration and the status band — against the visible
	/// right bound, inside any rail reservation — so the gap reads as
	/// session identity instead of dead space.
	fn draw_session_title(frame: &mut Frame, y: u16, right_inset: u16) {
		let width = frame.size().width.saturating_sub(right_inset);
		let title_width = visible_width(SESSION_TITLE);
		if y >= frame.size().height || width < title_width.saturating_add(2) {
			return;
		}
		let x = width.saturating_sub(title_width.saturating_add(1));
		draw_line(frame, x, y, title_width, &[Span::new(SESSION_TITLE, ink(FAINT).italic())]);
	}
}

/// The closed four-row command box that opens the transcript.
fn draw_command_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 4 || rect.height < 4 {
		return;
	}

	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	let header = [
		Span::new(" PARALLEL TEST RUN ", panel_ink(GREEN).bold()),
		Span::new("results append below · live rows in the bottom panel", panel_ink(MUTED)),
	];
	draw_line(frame, content_x, rect.y + 1, content_width, &header);
	let command = [
		Span::new("$ ", panel_ink(MUTED)),
		Span::new("bun test --parallel=8", panel_ink(CYAN)),
		Span::new(" --timeout=30000 --all-workspaces", panel_ink(TEXT)),
	];
	draw_line(frame, content_x, rect.y + 2, content_width, &command);
}

/// The live band's shard panel: twelve mutable rows that repaint in place
/// every frame and never enter native scrollback.
fn draw_live_panel(
	frame: &mut Frame,
	rows: &mut [LiveRowCache; LIVE_SHARD_ROWS as usize],
	label_scratch: &mut StrMut,
	rect: Rect,
	repaint_chrome: bool,
	emitted_shards: u16,
	animation_frame: u64,
	charset: Charset,
) -> bool {
	let mut changed = repaint_chrome;
	if repaint_chrome {
		draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	}
	if rect.width < 4 || rect.height < 3 {
		return changed;
	}

	if repaint_chrome {
		let title = [
			Span::new(" LIVE SHARDS ", panel_ink(GREEN).bold()),
			Span::new("mutable rows repaint in place ", panel_ink(MUTED)),
		];
		draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	}
	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	for row in 0..rect.height.saturating_sub(2) {
		let shard = emitted_shards.saturating_add(row).saturating_add(1);
		let phase = (u64::from(row) + animation_frame) % 11;
		let (prefix_phase, symbol, state, state_style, progress) = match phase {
			0 => (
				0,
				"⠼",
				"running",
				panel_ink(GREEN).bold(),
				(u64::from(row) * 17 + animation_frame * 7) % 100,
			),
			1..=7 => {
				(1, "·", "working", panel_ink(MUTED), (u64::from(row) * 17 + animation_frame * 7) % 100)
			},
			_ => (2, "·", "queued ", panel_ink(FAINT), 0),
		};
		let row_y = rect.y + 1 + row;
		let right = content_x
			.saturating_add(content_width)
			.min(frame.size().width);
		let cache = &mut rows[usize::from(row)];
		let prefix_changed = repaint_chrome
			|| !cache.prefix_valid
			|| cache.prefix_shard != shard
			|| cache.prefix_phase != prefix_phase;
		changed |= prefix_changed;
		let label_x = if prefix_changed {
			let prefix = fmts!(" {symbol} shard {shard:03} ");
			let prefix_width = prefix.len().saturating_sub(symbol.len()).saturating_add(1);
			let next_x = content_x
				.saturating_add(u16::try_from(prefix_width).unwrap_or(u16::MAX))
				.saturating_add(u16::try_from(state.len()).unwrap_or(u16::MAX))
				.saturating_add(2)
				.min(right);
			if !repaint_chrome && cache.label_x != next_x {
				clear_cached_label(frame, cache, row_y, right);
			}
			let next_x = draw_line(frame, content_x, row_y, content_width, &[
				Span::new(prefix.as_str(), state_style),
				Span::new(state, state_style),
				Span::new("  ", panel_ink(FAINT)),
			]);
			cache.prefix_shard = shard;
			cache.prefix_phase = prefix_phase;
			cache.prefix_valid = true;
			next_x
		} else {
			cache.label_x
		};
		let moved = cache.label_x != label_x;
		let label_changed = repaint_chrome
			|| moved
			|| !cache.label_valid
			|| cache.label_shard != shard
			|| cache.label_progress != progress;
		changed |= label_changed;
		if label_changed {
			label_scratch.truncate(0);
			write!(label_scratch, "workspace-{shard:03}.test.ts  [{progress:>3}%]")
				.expect("shard label formatting is infallible");
			let resized = cache.label.len() != label_scratch.len();
			if !repaint_chrome && resized && !moved {
				clear_cached_label(frame, cache, row_y, right);
			}
			let width = right.saturating_sub(label_x);
			if repaint_chrome || moved || resized {
				frame.put_clipped(label_x, row_y, width, label_scratch.as_str(), panel_ink(MUTED));
			} else {
				draw_ascii_changes(
					frame,
					label_x,
					row_y,
					width,
					cache.label.as_str(),
					label_scratch.as_str(),
					panel_ink(MUTED),
				);
			}
			std::mem::swap(&mut cache.label, label_scratch);
			cache.label_shard = shard;
			cache.label_progress = progress;
			cache.label_valid = true;
		}
		cache.label_x = label_x;
	}
	changed
}

fn clear_cached_label(frame: &mut Frame, cache: &LiveRowCache, y: u16, right: u16) {
	if cache.label.is_empty() {
		return;
	}
	let width = u16::try_from(cache.label.len())
		.unwrap_or(u16::MAX)
		.min(right.saturating_sub(cache.label_x));
	frame.fill(Rect::new(cache.label_x, y, width, 1), panel_style());
}

/// Repaints only changed byte runs within an equal-length ASCII label.
fn draw_ascii_changes(
	frame: &mut Frame,
	x: u16,
	y: u16,
	width: u16,
	previous: &str,
	next: &str,
	style: Style,
) {
	if width == 0 || previous == next {
		return;
	}
	if previous.len() != next.len() || !previous.is_ascii() || !next.is_ascii() {
		frame.put_clipped(x, y, width, next, style);
		return;
	}
	let previous = previous.as_bytes();
	let next_bytes = next.as_bytes();
	let limit = previous.len().min(usize::from(width));
	let mut index = 0;
	while index < limit {
		while index < limit && previous[index] == next_bytes[index] {
			index += 1;
		}
		let start = index;
		while index < limit && previous[index] != next_bytes[index] {
			index += 1;
		}
		if start < index {
			let offset = u16::try_from(start).unwrap_or(u16::MAX);
			frame.put_clipped(
				x.saturating_add(offset),
				y,
				u16::try_from(index - start).unwrap_or(u16::MAX),
				&next[start..index],
				style,
			);
		}
	}
}

fn draw_edit_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 8 || rect.height < EDIT_BOX_HEIGHT {
		return;
	}

	let title = [
		Span::new(" Live ", panel_ink(GREEN).bold()),
		Span::new("band · selection semantics ", panel_ink(CYAN)),
	];
	draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	draw_line(frame, rect.x + 2, rect.y + 1, rect.width.saturating_sub(4), &[
		Span::new(charset.check(), panel_ink(GREEN).bold()),
		Span::new(" ", panel_ink(GREEN)),
		Span::new("Transcript selections ride with the text", panel_ink(TEXT)),
	]);
	draw_line(frame, rect.x + 2, rect.y + 2, rect.width.saturating_sub(4), &[Span::new(
		"  margin commits pin the band on kitty-class terminals",
		panel_ink(MUTED),
	)]);
}

/// Paints a submitted message: the prompt gutter, then the rendered
/// Markdown document blitted beside it (or the raw lines when the text
/// isn't renderable as Markdown).
fn draw_submission(frame: &mut Frame, y: u16, submission: &Submission, charset: Charset) {
	if frame.size().width < 4 {
		return;
	}
	let Some(view) = &submission.view else {
		for (offset, line) in submission.text.split('\n').enumerate() {
			let Ok(offset) = u16::try_from(offset) else {
				break;
			};
			let row = y.saturating_add(offset);
			if row >= frame.size().height {
				break;
			}
			let prompt = if offset == 0 { charset.cursor() } else { "  " };
			let text_x = frame.put(1, row, prompt, ink(GREEN).bold());
			let width = frame
				.size()
				.width
				.saturating_sub(1)
				.saturating_sub(text_x.saturating_sub(1));
			draw_submission_text(frame, text_x, row, width, line, charset);
		}
		return;
	};
	frame.put(1, y, charset.cursor(), ink(GREEN).bold());
	frame.blit(view.frame(), 0, view.height(), 3, y);
}
fn explicit_line_count(text: &str) -> u16 {
	u16::try_from(
		text
			.bytes()
			.filter(|byte| *byte == b'\n')
			.count()
			.saturating_add(1),
	)
	.unwrap_or(u16::MAX)
}

/// Paints a rounded panel box through the tier's border glyphs.
fn draw_box(frame: &mut Frame, rect: Rect, border: Style, fill: Style, charset: Charset) {
	if rect.width == 0 || rect.height == 0 {
		return;
	}
	let (tl, tr, _, _, horizontal, vertical) = charset.border(Border::Round);
	frame.fill(rect, fill);
	let mut glyph = [0_u8; 4];
	if rect.width == 1 {
		frame.put(rect.x, rect.y, vertical.encode_utf8(&mut glyph), border);
		return;
	}

	let right = rect.x + rect.width - 1;
	let bottom = rect.y + rect.height - 1;
	frame.put(rect.x, rect.y, tl.encode_utf8(&mut glyph), border);
	frame.put(right, rect.y, tr.encode_utf8(&mut glyph), border);
	for x in rect.x + 1..right {
		frame.put(x, rect.y, horizontal.encode_utf8(&mut glyph), border);
	}

	if rect.height > 1 {
		draw_box_bottom(frame, rect, border, charset);
	}
	for row in rect.y + 1..bottom {
		frame.put(rect.x, row, vertical.encode_utf8(&mut glyph), border);
		frame.put(right, row, vertical.encode_utf8(&mut glyph), border);
	}
}

fn draw_box_bottom(frame: &mut Frame, rect: Rect, border: Style, charset: Charset) {
	if rect.width < 2 || rect.height < 2 {
		return;
	}
	let (_, _, bl, br, horizontal, _) = charset.border(Border::Round);
	let mut glyph = [0_u8; 4];
	let right = rect.x + rect.width - 1;
	let bottom = rect.y + rect.height - 1;
	frame.put(rect.x, bottom, bl.encode_utf8(&mut glyph), border);
	frame.put(right, bottom, br.encode_utf8(&mut glyph), border);
	for x in rect.x + 1..right {
		frame.put(x, bottom, horizontal.encode_utf8(&mut glyph), border);
	}
}

fn draw_line(frame: &mut Frame, x: u16, y: u16, width: u16, spans: &[Span<'_>]) -> u16 {
	let right = x.saturating_add(width).min(frame.size().width);
	let mut column = x;
	for span in spans {
		column = frame.put_clipped(column, y, right.saturating_sub(column), span.text, span.style);
		if column >= right {
			break;
		}
	}
	column
}

/// Flows `spans` grapheme-exact across the rect like a bare terminal,
/// preserving all whitespace and flagging each exactly-filled row boundary
/// soft so native selection copies the paragraph as one unbroken line.
/// Returns the rows used.
fn draw_flowed(frame: &mut Frame, rect: Rect, spans: &[Span<'_>]) -> u16 {
	if rect.width == 0 || rect.height == 0 {
		return 0;
	}
	let full_row = rect.x == 0 && rect.width == frame.size().width;
	let mut row = 0_u16;
	let mut column = 0_u16;
	let mut drew_anything = false;

	for span in spans {
		for grapheme in xutf::graphemes_str(span.text) {
			let grapheme_width = visible_width(grapheme);
			if grapheme_width == 0 || grapheme_width > rect.width {
				continue;
			}
			if column.saturating_add(grapheme_width) > rect.width {
				// Only an exactly-filled row is byte-joinable by autowrap.
				if full_row && column == rect.width {
					frame.set_soft_wrap(rect.y.saturating_add(row));
				}
				row += 1;
				column = 0;
			}
			if row >= rect.height {
				return rect.height;
			}
			frame.put(rect.x + column, rect.y + row, grapheme, span.style);
			column += grapheme_width;
			drew_anything = true;
		}
	}

	if drew_anything { row + 1 } else { 0 }
}

examples/chat/picker.rs (line 319)

	pub fn layer(&mut self, viewport: Size) -> Layer<'_> {
		let rows = (viewport.height * 2 / 5).saturating_sub(FRAME_ROWS).max(5);
		let tier = PerfTier::of(viewport.width);
		if tier != self.tier {
			self.tier = tier;
			self.rebuild();
		}
		if rows != self.rows {
			self.rows = rows;
			// One query row plus the windowed list.
			self.ui.set_prop("models", Prop::H, rows.saturating_add(1));
		}
		if self.ui.frame().size().width != viewport.width {
			self.ui.resize(viewport.width);
		}
		Layer { frame: self.ui.frame(), options: &self.options, active: true }
	}

	/// Applies one surfaced [`UiEvent`] to picker state.
	fn route(&mut self, event: UiEvent) -> PickerEvent {
		match event {
			UiEvent::Cancel => PickerEvent::Close,
			UiEvent::Changed { value, .. } => value
				.as_str()
				.parse()
				.map_or(PickerEvent::Consumed, PickerEvent::Pick),
			UiEvent::Highlighted { value, .. } => {
				self.show_detail(value.as_str().parse().ok());
				PickerEvent::Consumed
			},
			UiEvent::Filtered { query, value, .. } => {
				let wants_roles = query.starts_with('@');
				self.query = query;
				if wants_roles == (self.mode == Mode::Roles) {
					self.show_detail(value.and_then(|value| value.as_str().parse().ok()));
				} else {
					self.mode = if wants_roles {
						Mode::Roles
					} else {
						Mode::Models
					};
					self.rebuild();
				}
				PickerEvent::Consumed
			},
			UiEvent::None | UiEvent::Submit | UiEvent::Pressed(_) => PickerEvent::Consumed,
		}
	}

	/// Rebuilds the retained tree for the current mode/tier, reseeding the
	/// select's query so typing continuity survives the swap.
	fn rebuild(&mut self) {
		let width = self.ui.frame().size().width;
		self.ui = build(self.mode, self.tier, self.current, &self.query, self.rows, width, &self.ctx);
		let initial = match self.mode {
			Mode::Models => Some(self.current),
			// The role list keeps its configured order; detail follows the
			// first row until the next cursor event.
			Mode::Roles => ROLES.first().map(|role| role.model),
		};
		self.show_detail(initial);
	}

examples/chat/commands.rs (line 118)

	pub fn layer(&mut self, viewport: Size) -> Layer<'_> {
		let width = (viewport.width * 3 / 5).max(48).min(viewport.width);
		let rows = (viewport.height / 2).saturating_sub(FRAME_ROWS).max(5);
		if rows != self.rows {
			self.rows = rows;
			// One query row plus the windowed list.
			self
				.ui
				.set_prop("commands", Prop::H, rows.saturating_add(1));
		}
		if self.ui.frame().size().width != width {
			self.ui = build(&self.query, self.rows, width, &self.ctx);
		}
		self.options = self.options.width(Dim::Cells(width));
		Layer { frame: self.ui.frame(), options: &self.options, active: true }
	}

examples/tml.rs (line 73)

async fn main() -> io::Result<()> {
	let path = std::env::args()
		.nth(1)
		.unwrap_or_else(|| "example.tml".into());
	let source = std::fs::read_to_string(&path)?;

	let mut ctx = None;
	let mut app = AppOptions::new()
		.quit([Key::Ctrl('c'), Key::Char('q'), Key::Esc])
		.start(|env| {
			let ui = build(&source, env.viewport.width, &env.ctx);
			ctx = Some(env.ctx);
			ui
		})
		.await?;
	let ctx = ctx.expect("start ran the builder");

	let handle = app.handle();
	tokio::spawn(async move {
		let mut seen = modified(path.as_ref());
		loop {
			tokio::time::sleep(Duration::from_millis(150)).await;
			let stamp = modified(path.as_ref());
			if stamp == seen {
				continue;
			}
			seen = stamp;
			let Ok(source) = std::fs::read_to_string(&path) else {
				continue;
			};
			let ctx = ctx.clone();
			handle.update(move |ui| *ui = build(&source, ui.frame().size().width, &ctx));
		}
	});

	while app.next().await?.is_some() {}
	Ok(())
}

examples/chat/main.rs (line 752)

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/chat/welcome.rs (line 204)

	pub fn render(&mut self, viewport: Size, elapsed: Duration) -> &Frame {
		if self.frame.size() != viewport {
			self.frame = Frame::new(viewport);
			self.backdrop_frame = Frame::new(viewport);
			self.backdrop_at = None;
		}
		let clock = elapsed;
		let elapsed = elapsed.as_secs_f32();
		// Exponential pointer chase, frame-rate independent (~100ms lag).
		let delta = (elapsed - self.last_elapsed).max(0.0);
		self.last_elapsed = elapsed;
		let response = 1.0 - (-delta * 10.0).exp();
		self.camera.0 += (self.camera_target.0 - self.camera.0) * response;
		self.camera.1 += (self.camera_target.1 - self.camera.1) * response;
		self.draw_backdrop(viewport, clock, elapsed);

		let logo_interval = ambient_interval(clock, LOGO_IDLE_INTERVAL);
		if self
			.logo_at
			.is_none_or(|rendered_at| clock.saturating_sub(rendered_at) >= logo_interval)
		{
			self.logo = logo_cells(elapsed, self.camera);
			self.logo_at = Some(clock);
		}
		let cols = if viewport.width >= CARD_COLS && viewport.height >= CARD_ROWS {
			Some(CARD_COLS)
		} else if viewport.width >= SMOL_COLS && viewport.height >= CARD_ROWS {
			Some(SMOL_COLS)
		} else {
			None
		};
		let Some(cols) = cols else {
			let left = viewport.width.saturating_sub(LOGO_COLS as u16) / 2;
			let top = viewport.height.saturating_sub(LOGO_ROWS as u16) / 2;
			self.logo_origin = (left, top);
			blit_logo(&mut self.frame, &self.logo, left, top, PLATE);
			return &self.frame;
		};

		let left = (viewport.width - cols) / 2;
		let top = (viewport.height - CARD_ROWS) / 2;
		let hovered = self.pointer.is_some_and(|(x, y)| {
			(left..left + cols).contains(&x) && (top..top + CARD_ROWS).contains(&y)
		});
		self
			.hover
			.retarget(clock, if hovered { 1.0 } else { 0.0 }, HOVER_EASE, Easing::EaseOut);
		let hover = self.hover.sample(clock).clamp(0.0, 1.0);
		self.draw_card(cols, left, top, elapsed, hover);
		&self.frame
	}

Additional examples can be found in:

• examples/footers.rs

pub const fn set_cursor(&mut self, x: u16, y: u16)

Places the terminal’s hardware cursor at a document cell.

The renderer hides the cursor when this cell falls outside the live viewport.

Examples found in repository

examples/chat/demo.rs (lines 468-473)

	fn paint(&mut self, pc: &mut PaintCtx<'_>, rect: Rect) {
		pc.hits
			.push(Hit { rect, slot: self.slot, tag: HitTag::Press });
		let editor = self.editor.borrow();
		let input_x = rect.x.saturating_add(Self::input_offset());
		let input_width = Self::input_width(rect.width);
		let input_height = editor.input_height_for(input_width);
		let theme = Theme::default();
		let mut in_comment = false;
		for (offset, row) in editor.view(input_width).iter().enumerate() {
			let row_y = rect
				.y
				.saturating_add(u16::try_from(offset).unwrap_or(u16::MAX));
			if row_y >= pc.clip {
				break;
			}
			if offset == 0 {
				pc.frame
					.put(rect.x, row_y, &Self::input_prompt(pc.ctx.charset), ink(FAINT));
			}
			let mut spans: SmallVec<Span<'_>, 16> = SmallVec::new();
			if editor.options().xml {
				let (runs, next) = highlight_xml(row.text, &theme, in_comment);
				in_comment = next;
				push_row_spans(&editor, row.text, &runs, &mut spans);
			} else {
				push_row_spans(&editor, row.text, &[], &mut spans);
			}
			draw_line(pc.frame, input_x, row_y, input_width, &spans);
			if let Some(cursor_column) = row.cursor_column {
				if cursor_column >= visible_width(row.text)
					&& let Some(hint) = editor.inline_hint()
				{
					let hint_x = input_x.saturating_add(cursor_column).saturating_add(1);
					let width = input_width.saturating_sub(cursor_column.saturating_add(1));
					draw_line(pc.frame, hint_x, row_y, width, &[Span::new(
						hint.as_str(),
						ink(MUTED).dim(),
					)]);
				}
				pc.frame.set_cursor(
					input_x
						.saturating_add(cursor_column)
						.min(rect.x.saturating_add(rect.width.saturating_sub(2))),
					row_y,
				);
			}
		}
		Self::paint_picker(pc, rect, rect.y.saturating_add(input_height), &editor);
	}

pub fn clear(&mut self, style: Style)

Replaces every cell with a styled blank.

pub fn fill(&mut self, rect: Rect, style: Style)

Fills a clipped rectangle with styled blanks.

Examples found in repository

examples/chat/welcome.rs (line 266)

	fn draw_backdrop(&mut self, viewport: Size, clock: Duration, elapsed: f32) {
		let interval = ambient_interval(clock, BACKDROP_IDLE_INTERVAL);
		if self
			.backdrop_at
			.is_none_or(|rendered_at| clock.saturating_sub(rendered_at) >= interval)
		{
			let fade = smooth((elapsed / BACKDROP_FADE).clamp(0.0, 1.0));
			self
				.backdrop_frame
				.fill(Rect::new(0, 0, viewport.width, viewport.height), Style::default());
			let frame = &mut self.backdrop_frame;
			let mut buffer = [0_u8; 4];
			let dim = |color: Color| Color::Rgb(0, 0, 0).lerp(color, fade);
			self.surface.render(
				&mut self.backdrop,
				clock,
				viewport.width,
				viewport.height,
				|x, y, glyph, fg, bg| {
					let style = Style::new().fg(dim(fg));
					let style = match bg {
						Some(bg) => style.bg(dim(bg)),
						None => style,
					};
					frame.put(x, y, glyph.encode_utf8(&mut buffer), style);
				},
			);
			self.backdrop_at = Some(clock);
		}
		self.frame.clone_from(&self.backdrop_frame);
	}

	fn draw_card(&mut self, cols: u16, left: u16, top: u16, elapsed: f32, hover: f32) {
		let full = cols == CARD_COLS;
		let logo_left = if full {
			left + 3
		} else {
			left + (cols - LOGO_COLS as u16) / 2
		};
		self.logo_origin = (logo_left, top + 2);
		// Pointer-tracking border glow: the brand gradient sampled by angle
		// around the card center (the disk's own palette), strongest near
		// the pointer, scaled by the eased hover amount.
		let pointer = self.pointer;
		let center =
			(f32::from(left) + f32::from(cols) / 2.0, f32::from(top) + f32::from(CARD_ROWS) / 2.0);
		let edge_at = move |x: u16, y: u16| -> Style {
			let Some((px, py)) = pointer.filter(|_| hover > 0.02) else {
				return on_card(CARD_BORDER);
			};
			let dx = (f32::from(x) - f32::from(px)) * 0.5;
			let dy = f32::from(y) - f32::from(py);
			let glow = hover * (-(dx * dx + dy * dy) / 34.0).exp();
			if glow < 0.02 {
				return on_card(CARD_BORDER);
			}
			let angle = (f32::from(y) - center.1).atan2((f32::from(x) - center.0) * 0.5);
			let brand = vec3_color(gradient(angle - elapsed * 0.5));
			on_card(CARD_BORDER.lerp(brand, glow))
		};
		let frame = &mut self.frame;
		frame.fill(Rect::new(left, top, cols, CARD_ROWS), on_card(TEXT));

		let right = left + cols - 1;
		let bottom = top + CARD_ROWS - 1;
		let divider = bottom - 2;
		let (tl, tr, bl, br, horizontal, vertical) = self.charset.border(Border::Round);
		let grid = self.charset.grid();
		let mut glyph = [0_u8; 4];
		frame.put(left, top, tl.encode_utf8(&mut glyph), edge_at(left, top));
		frame.put(right, top, tr.encode_utf8(&mut glyph), edge_at(right, top));
		frame.put(left, divider, grid.middle.0.encode_utf8(&mut glyph), edge_at(left, divider));
		frame.put(right, divider, grid.middle.2.encode_utf8(&mut glyph), edge_at(right, divider));
		frame.put(left, bottom, bl.encode_utf8(&mut glyph), edge_at(left, bottom));
		frame.put(right, bottom, br.encode_utf8(&mut glyph), edge_at(right, bottom));
		for x in left + 1..right {
			frame.put(x, top, horizontal.encode_utf8(&mut glyph), edge_at(x, top));
			frame.put(x, divider, horizontal.encode_utf8(&mut glyph), edge_at(x, divider));
			frame.put(x, bottom, horizontal.encode_utf8(&mut glyph), edge_at(x, bottom));
		}
		for y in top + 1..bottom {
			if y != divider {
				frame.put(left, y, vertical.encode_utf8(&mut glyph), edge_at(left, y));
				frame.put(right, y, vertical.encode_utf8(&mut glyph), edge_at(right, y));
			}
		}

		frame.put(left + 2, top, self.title.as_str(), on_card(TEXT_STRONG));
		if full {
			frame.put(left + 34, top, " SESSION ORBIT ", on_card(FAINT));
			draw_dust(frame, left, top, elapsed);
			draw_sessions(frame, left, top, self.charset);
			draw_beam(frame, left, top, elapsed);
		}

		blit_logo(frame, &self.logo, logo_left, top + 2, CARD_BG);

		let footer = divider + 1;
		frame.fill(Rect::new(left + 1, footer, cols - 2, 1), on_footer(TEXT));
		if full {
			frame.put(left + 3, divider, " SHORTCUTS ", on_card(FAINT));
			let dot = fmts!(" {} ", self.charset.icon(Icon::Enabled));
			let x = frame.put(left + cols - 21, top, &dot, on_card(GREEN));
			frame.put(x, top, "rust-analyzer ", on_card(MUTED));
			draw_full_hints(frame, left, footer);
		} else {
			draw_smol_hints(frame, left, cols, footer);
		}
	}
}

impl Default for Welcome {
	fn default() -> Self {
		Self::new(Charset::NerdFont)
	}
}

fn draw_dust(frame: &mut Frame, left: u16, top: u16, elapsed: f32) {
	for &(x, y, offset) in &DUST {
		let pulse = 0.5 + 0.5 * (elapsed * 1.4 + offset).sin();
		let color = FAINT.lerp(CYAN, pulse * 0.28);
		frame.put(left + x, top + y, "·", on_card(color));
	}
	frame.put(left + 1, top + 7, HORIZON, on_card(FAINT.lerp(INDIGO, 0.16)));
	frame.put(left + 14, top + 1, "+Z", on_card(FAINT));
}

fn draw_beam(frame: &mut Frame, left: u16, top: u16, elapsed: f32) {
	let phase = (elapsed * 9.0) as usize % BEAM.len();
	for (index, &(x, y, glyph)) in BEAM.iter().enumerate() {
		let direct = index.abs_diff(phase);
		let distance = direct.min(BEAM.len() - direct);
		let color = match distance {
			0 => TEXT_STRONG,
			1 => CYAN,
			_ => FAINT.lerp(INDIGO, 0.34),
		};
		frame.put(left + x, top + y, glyph, on_card(color));
	}
}

fn draw_sessions(frame: &mut Frame, left: u16, top: u16, charset: Charset) {
	let (_, _, _, _, _, vertical) = charset.border(Border::Round);
	let mut glyph = [0_u8; 4];
	let panel_x = left + 36;
	frame.put(panel_x, top + 2, "RECENT SESSIONS", on_card(MUTED));
	frame.put(left + CARD_COLS - 14, top + 2, "4 / LOCAL", on_card(FAINT));
	for y in top + 4..=top + 10 {
		frame.put(panel_x, y, vertical.encode_utf8(&mut glyph), on_card(FAINT.lerp(INDIGO, 0.18)));
	}
	for (index, (label, age)) in SESSIONS.iter().enumerate() {
		let y = top + 4 + index as u16 * 2;
		if index == 0 {
			frame.fill(Rect::new(panel_x - 2, y, CARD_COLS - 35, 1), on_selected(TEXT));
			frame.put(panel_x - 2, y, charset.rail(), on_selected(GREEN));
			frame.put(panel_x, y, charset.radio(true), on_selected(GREEN));
			frame.put(panel_x + 2, y, age, on_selected(GREEN));
			frame.put(panel_x + 7, y, label, on_selected(TEXT_STRONG));
		} else {
			frame.put(panel_x, y, charset.radio(false), on_card(FAINT));
			frame.put(panel_x + 2, y, age, on_card(FAINT));
			frame.put(panel_x + 7, y, label, on_card(MUTED));
		}
	}
}

examples/footers.rs (line 118)

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

/// Per-frame paint inputs shared by every study.
struct Scene {
	charset: Charset,
	width:   u16,
	elapsed: Duration,
}

impl Scene {
	const fn spinner(&self) -> &'static str {
		self.charset.spinner().at(self.elapsed)
	}

	fn timer(&self) -> Str {
		let seconds = self.elapsed.as_secs();
		if seconds < 60 {
			fmts!("{seconds}s")
		} else {
			fmts!("{}m", seconds / 60)
		}
	}

	const fn right_edge(&self) -> u16 {
		self.width.saturating_sub(1)
	}
}

/// One study: a header line and a `rows`-tall live mock beneath it.
struct Study {
	title: &'static str,
	note:  &'static str,
	rows:  u16,
	draw:  fn(&mut Frame, u16, &Scene),
}

const STUDIES: [Study; 6] = [
	Study {
		title: "pi parity",
		note:  "border carries the band left and the title right; the intent rides its own spinner \
		        row",
		rows:  4,
		draw:  study_pi_parity,
	},
	Study {
		title: "gap title",
		note:  "the air row earns its keep — session title idles right-aligned in the gap",
		rows:  4,
		draw:  study_gap_title,
	},
	Study {
		title: "band title",
		note:  "title as the left band's second segment; session facts dock right",
		rows:  4,
		draw:  study_band_title,
	},
	Study {
		title: "prompt title",
		note:  "split + air untouched; the title rests on the prompt row and yields while typing",
		rows:  4,
		draw:  study_prompt_title,
	},
	Study {
		title: "crown",
		note:  "title crowns the whole block; narration, gap, and split bands breathe below it",
		rows:  5,
		draw:  study_crown,
	},
	Study {
		title: "hem",
		note:  "title stitched into the top border, band into the bottom hem",
		rows:  4,
		draw:  study_hem,
	},
];

/// Renders the full document — title block plus every study — at width.
fn compose(scene: &Scene) -> Frame {
	let height = STUDIES
		.iter()
		.map(|study| study.rows + 3)
		.fold(3_u16, u16::saturating_add);
	let mut frame = Frame::new(Size::new(scene.width, height));
	frame.fill(Rect::new(0, 0, scene.width, height), ink(TEXT));

	let column = frame.put(1, 0, "composer footer studies", ink(TEXT).bold());
	frame.put(
		column.saturating_add(2),
		0,
		"split + air gap, six session-title placements",
		ink(MUTED),
	);
	frame.put(1, 1, "↑/↓ scroll · PgUp/PgDn page · Home/End jump · q quits", ink(FAINT));

	let mut y = 3_u16;
	for (index, study) in STUDIES.iter().enumerate() {
		let number = fmts!("{:>2} ", index + 1);
		let mut column = frame.put(1, y, &number, ink(GOLD).bold());
		column = frame.put(column, y, study.title, ink(TEXT).bold());
		column = frame.put(column, y, "  ", ink(FAINT));
		frame.put(column, y, study.note, ink(MUTED));
		(study.draw)(&mut frame, y + 1, scene);
		y = y.saturating_add(study.rows + 3);
	}
	frame
}

examples/chat/demo.rs (lines 1080-1088)

	fn render_at(&mut self, viewport: Size, elapsed: Duration) -> RenderedFrame<'_> {
		if viewport.width == 0 || viewport.height == 0 {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			self.live_panel = None;
			self.frame = Frame::new(viewport);
			return RenderedFrame {
				frame:       &self.frame,
				stable_rows: 0,
				damage:      SmallVec::new(),
			};
		}
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		// Fires due animation wakes (the status bar's spinner and brand
		// fade) so the blit below picks up fresh retained pixels.
		self.editor_ui.tick(elapsed);
		let editor_changed = self.editor_ui.take_frame_damage();

		// A viewport change starts a fresh renderer session: replay the
		// whole transcript log at the new width. Between rebuilds the log
		// is append-only and every drawn row is final, so selections over
		// transcript text stay anchored to it in every terminal.
		let rebuild = self.last_viewport != viewport;
		if rebuild {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			let message_width = Self::message_width(viewport.width);
			for entry in &mut self.transcript {
				if let Entry::Submitted(submission) = entry {
					submission.resize(message_width, &self.ctx);
				}
			}
		}
		while self.appended_messages < Self::visible_messages(elapsed) {
			self.transcript.push(Entry::Message(self.appended_messages));
			self.appended_messages += 1;
		}
		while self.emitted_shards < Self::finished_shards(elapsed) {
			self.emitted_shards += 1;
			self.transcript.push(Entry::ShardDone(self.emitted_shards));
		}

		let mut new_rows = 0_u16;
		for entry in &self.transcript[self.drawn_entries..] {
			new_rows = new_rows.saturating_add(Self::entry_height(entry, viewport.width, &self.ctx));
		}
		let transcript_rows = self.transcript_rows.saturating_add(new_rows);
		let editor_height = self.editor_ui.height();
		// Native scrollback is append-only, so the logical document may
		// never shrink while the seam is live: band rows that close again
		// (extra input lines) become blank padding that heals as the
		// transcript grows.
		let natural_height = transcript_rows.saturating_add(Self::band_height(editor_height));
		self.height_floor = self.height_floor.max(natural_height);
		let document_height = self.height_floor.max(viewport.height);
		let transcript_damage_start = if rebuild { 0 } else { self.transcript_rows };
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_y = document_height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		let panel = Rect::new(margin, panel_y, content_width, panel_height);
		let repaint_suffix = rebuild || new_rows > 0 || self.live_panel != Some(panel);
		if rebuild {
			self.frame = Frame::new(Size::new(viewport.width, document_height));
		} else {
			self.frame.resize_height(document_height, base_style());
		}
		if repaint_suffix {
			self.frame.fill(
				Rect::new(
					0,
					transcript_damage_start,
					viewport.width,
					document_height.saturating_sub(transcript_damage_start),
				),
				base_style(),
			);
		}

		// Paint the new transcript entries; rows above `transcript_rows`
		// are final and never repainted.
		let mut y = self.transcript_rows;
		for index in self.drawn_entries..self.transcript.len() {
			let used = self.draw_entry_at(index, y, viewport.width);
			y = y.saturating_add(used);
		}
		self.drawn_entries = self.transcript.len();
		self.transcript_rows = y;

		// The live band repaints in place at the bottom of the document.
		let animation_frame = Self::animation_frame(elapsed);
		let panel_changed = draw_live_panel(
			&mut self.frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			panel,
			repaint_suffix,
			self.emitted_shards,
			animation_frame,
			self.ctx.charset,
		);
		let working = self.work.borrow().working;
		let working_changed = self.last_working != working;
		if !repaint_suffix && self.last_working && !working {
			self
				.frame
				.fill(Rect::new(0, working_y, viewport.width, 1), base_style());
		}
		if working {
			Self::draw_working(&mut self.frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut self.frame, title_y, self.right_inset);
		if repaint_suffix || editor_changed {
			self
				.frame
				.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);
		}
		let mut damage = SmallVec::new();
		if repaint_suffix {
			damage.push((transcript_damage_start, document_height));
		} else {
			if panel_changed {
				damage.push((panel_y, panel_y.saturating_add(panel_height)));
			}
			if working || working_changed {
				damage.push((working_y, working_y.saturating_add(1)));
			}
			if editor_changed {
				damage.push((editor_y, document_height));
			}
		}
		self.last_working = working;
		self.live_panel = Some(panel);

		RenderedFrame { frame: &self.frame, stable_rows: self.transcript_rows, damage }
	}

	fn generation(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / EMIT_INTERVAL.as_millis()).unwrap_or(u64::MAX)
	}

	fn animation_frame(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / 80).unwrap_or(u64::MAX)
	}

	fn visible_messages(elapsed: Duration) -> usize {
		let interval = MESSAGE_INTERVAL.as_millis();
		usize::try_from(elapsed.as_millis() / interval + 1)
			.unwrap_or(usize::MAX)
			.min(4)
	}

	/// Shards whose permanent result line has been appended by `elapsed`:
	/// two per emit tick, capped well inside `u16` document heights.
	fn finished_shards(elapsed: Duration) -> u16 {
		u16::try_from(Self::generation(elapsed).saturating_mul(2).min(60_000))
			.expect("finished shard count is clamped")
	}

	/// Rows the bottom live band occupies: the shard panel, a blank
	/// separator, the activity row, the title air row, and the editor
	/// block.
	const fn band_height(editor_height: u16) -> u16 {
		LIVE_SHARD_ROWS + 2 + 3 + editor_height
	}

	/// Rows `entry` will occupy at `width`, including its trailing blank.
	fn entry_height(entry: &Entry, width: u16, ctx: &UiContext) -> u16 {
		match entry {
			Entry::Command => 5,
			Entry::Message(message) => {
				let mut scratch = Frame::new(Size::new(width, 48));
				Self::draw_message(&mut scratch, 0, *message, width, ctx.charset)
			},
			Entry::ShardDone(_) => 1,
			Entry::Submitted(submission) => submission.height().saturating_add(1),
		}
	}

	const fn message_width(width: u16) -> u16 {
		let narrowed = width.saturating_sub(3);
		if narrowed == 0 { 1 } else { narrowed }
	}

	/// Paints one transcript entry at `y` and returns the rows it used.
	fn draw_entry_at(&mut self, index: usize, y: u16, width: u16) -> u16 {
		Self::draw_entry(&mut self.frame, &self.transcript[index], y, width, &self.ctx)
	}

	/// Paints `entry` into any frame at `y` and returns the rows it used,
	/// including the trailing blank.
	fn draw_entry(frame: &mut Frame, entry: &Entry, y: u16, width: u16, ctx: &UiContext) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		match entry {
			Entry::Command => {
				draw_command_box(frame, Rect::new(margin, y, content_width, 4), ctx.charset);
				5
			},
			Entry::Message(message) => Self::draw_message(frame, y, *message, width, ctx.charset),
			Entry::ShardDone(shard) => {
				Self::draw_shard_done(frame, y, *shard, width, ctx.charset);
				1
			},
			Entry::Submitted(submission) => {
				draw_submission(frame, y, submission, ctx.charset);
				submission.height().saturating_add(1)
			},
		}
	}

	/// Composes exactly one viewport of throwaway resize-drag content at the
	/// new geometry: the live band anchors to the bottom, then transcript
	/// entries are walked backward and rewrapped at `viewport.width` until
	/// the screen is full — O(viewport) work per drag frame, with the
	/// topmost entry sliced when it only partially fits. Retained transcript
	/// state is untouched, so the settle rebuild replays full history
	/// exactly once.
	pub fn render_resize_preview(&mut self, viewport: Size) -> Frame {
		let elapsed = self.started_at.elapsed();
		let mut frame = Frame::new(viewport);
		if viewport.width == 0 || viewport.height == 0 {
			return frame;
		}
		frame.fill(Rect::new(0, 0, viewport.width, viewport.height), base_style());
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		self.editor_ui.tick(elapsed);

		// The live band, laid out exactly like the retained document's.
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_height = self.editor_ui.height();
		let editor_y = viewport.height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		draw_live_panel(
			&mut frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			Rect::new(margin, panel_y, content_width, panel_height),
			true,
			self.emitted_shards,
			Self::animation_frame(elapsed),
			self.ctx.charset,
		);
		if self.work.borrow().working {
			Self::draw_working(&mut frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut frame, title_y, self.right_inset);
		frame.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);

		// Transcript tail, bottom-up above the band.
		let mut remaining = panel_y;
		for entry in self.transcript.iter().rev() {
			if remaining == 0 {
				break;
			}
			let height = Self::entry_height(entry, viewport.width, &self.ctx);
			if height == 0 {
				continue;
			}
			if height <= remaining {
				remaining -= height;
				Self::draw_entry(&mut frame, entry, remaining, viewport.width, &self.ctx);
			} else {
				// Slice the bottom rows of the partially visible entry.
				let mut scratch = Frame::new(Size::new(viewport.width, height));
				scratch.fill(Rect::new(0, 0, viewport.width, height), base_style());
				Self::draw_entry(&mut scratch, entry, 0, viewport.width, &self.ctx);
				frame.blit(&scratch, height - remaining, remaining, 0, 0);
				remaining = 0;
			}
		}
		frame
	}

	/// Paints the n-th scripted message and returns rows used including
	/// the trailing blank. Measurement draws into a scratch frame.
	fn draw_message(frame: &mut Frame, y: u16, message: usize, width: u16, charset: Charset) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		if message == 2 {
			draw_edit_box(frame, Rect::new(margin, y, content_width, EDIT_BOX_HEIGHT), charset);
			return EDIT_BOX_HEIGHT + 1;
		}
		let bottom = frame.size().height;
		let spans = Self::message_spans(message);
		// Prose flows edge-to-edge grapheme-exact — no side pads — so every
		// wrapped row re-joins byte-for-byte in native selection.
		let used = draw_flowed(frame, Rect::new(0, y, width, bottom.saturating_sub(y)), &spans);
		used.saturating_add(1)
	}

	fn message_spans(message: usize) -> SmallVec<Span<'static>, 3> {
		let mut spans = SmallVec::new();
		match message {
			0 => {
				spans.push(Span::new("Transcript rows are ", prose_style()));
				spans.push(Span::new("append-only", code_style()));
				spans.push(Span::new(
					": every line is painted once, becomes stable, and rides into native scrollback \
					 with any selection anchored to it.",
					prose_style(),
				));
			},
			1 => {
				spans.push(Span::new(
					"Only the bottom band repaints in place — the live shard panel, the activity \
					 shimmer, and the composer. Rows above it are never rewritten.",
					prose_style(),
				));
			},
			_ => {
				spans.push(Span::new(
					"On terminals that move margin-scrolled rows into scrollback, commits scroll only \
					 the stable transcript through a ",
					prose_style(),
				));
				spans.push(Span::new("DECSTBM top region", code_style()));
				spans.push(Span::new(", so the live band never shifts on screen.", prose_style()));
			},
		}
		spans
	}

	/// Appends a finished shard's permanent one-line result.
	fn draw_shard_done(frame: &mut Frame, y: u16, shard: u16, width: u16, charset: Charset) {
		let margin = u16::from(width >= 50);
		let prefix = fmts!(" {} shard {shard:03} passed", charset.check());
		let detail = fmts!("  workspace-{shard:03}.test.ts  [100%]");
		draw_line(frame, margin + 1, y, width.saturating_sub(margin * 2).saturating_sub(2), &[
			Span::new(prefix.as_str(), ink(GREEN)),
			Span::new(detail.as_str(), ink(MUTED)),
		]);
	}

	/// Shimmering activity line above the editor. The spinner and timer
	/// live in the status bar's brand segment; this row only narrates.
	fn draw_working(frame: &mut Frame, y: u16, elapsed: Duration, hint: &str) {
		if y >= frame.size().height || frame.size().width < 4 {
			return;
		}
		let start = u16::from(frame.size().width >= 50);
		let mut column = start;
		let length = xutf::graphemes_str(WORKING_MESSAGE)
			.count()
			.saturating_add(xutf::graphemes_str(hint).count())
			.saturating_add(1);
		let length = u16::try_from(length).unwrap_or(u16::MAX);
		let shimmer = Shimmer::new(elapsed, SHIMMER_PERIOD, length);
		let right = frame.size().width.saturating_sub(1);
		draw_shimmer(frame, &mut column, start, y, right, hint, shimmer, ink(CYAN));
		draw_shimmer(frame, &mut column, start, y, right, " ", shimmer, ink(GREEN));
		draw_shimmer(frame, &mut column, start, y, right, WORKING_MESSAGE, shimmer, ink(GREEN));
	}

	/// The session title resting right-aligned in the air row between
	/// the working narration and the status band — against the visible
	/// right bound, inside any rail reservation — so the gap reads as
	/// session identity instead of dead space.
	fn draw_session_title(frame: &mut Frame, y: u16, right_inset: u16) {
		let width = frame.size().width.saturating_sub(right_inset);
		let title_width = visible_width(SESSION_TITLE);
		if y >= frame.size().height || width < title_width.saturating_add(2) {
			return;
		}
		let x = width.saturating_sub(title_width.saturating_add(1));
		draw_line(frame, x, y, title_width, &[Span::new(SESSION_TITLE, ink(FAINT).italic())]);
	}
}

/// The closed four-row command box that opens the transcript.
fn draw_command_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 4 || rect.height < 4 {
		return;
	}

	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	let header = [
		Span::new(" PARALLEL TEST RUN ", panel_ink(GREEN).bold()),
		Span::new("results append below · live rows in the bottom panel", panel_ink(MUTED)),
	];
	draw_line(frame, content_x, rect.y + 1, content_width, &header);
	let command = [
		Span::new("$ ", panel_ink(MUTED)),
		Span::new("bun test --parallel=8", panel_ink(CYAN)),
		Span::new(" --timeout=30000 --all-workspaces", panel_ink(TEXT)),
	];
	draw_line(frame, content_x, rect.y + 2, content_width, &command);
}

/// The live band's shard panel: twelve mutable rows that repaint in place
/// every frame and never enter native scrollback.
fn draw_live_panel(
	frame: &mut Frame,
	rows: &mut [LiveRowCache; LIVE_SHARD_ROWS as usize],
	label_scratch: &mut StrMut,
	rect: Rect,
	repaint_chrome: bool,
	emitted_shards: u16,
	animation_frame: u64,
	charset: Charset,
) -> bool {
	let mut changed = repaint_chrome;
	if repaint_chrome {
		draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	}
	if rect.width < 4 || rect.height < 3 {
		return changed;
	}

	if repaint_chrome {
		let title = [
			Span::new(" LIVE SHARDS ", panel_ink(GREEN).bold()),
			Span::new("mutable rows repaint in place ", panel_ink(MUTED)),
		];
		draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	}
	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	for row in 0..rect.height.saturating_sub(2) {
		let shard = emitted_shards.saturating_add(row).saturating_add(1);
		let phase = (u64::from(row) + animation_frame) % 11;
		let (prefix_phase, symbol, state, state_style, progress) = match phase {
			0 => (
				0,
				"⠼",
				"running",
				panel_ink(GREEN).bold(),
				(u64::from(row) * 17 + animation_frame * 7) % 100,
			),
			1..=7 => {
				(1, "·", "working", panel_ink(MUTED), (u64::from(row) * 17 + animation_frame * 7) % 100)
			},
			_ => (2, "·", "queued ", panel_ink(FAINT), 0),
		};
		let row_y = rect.y + 1 + row;
		let right = content_x
			.saturating_add(content_width)
			.min(frame.size().width);
		let cache = &mut rows[usize::from(row)];
		let prefix_changed = repaint_chrome
			|| !cache.prefix_valid
			|| cache.prefix_shard != shard
			|| cache.prefix_phase != prefix_phase;
		changed |= prefix_changed;
		let label_x = if prefix_changed {
			let prefix = fmts!(" {symbol} shard {shard:03} ");
			let prefix_width = prefix.len().saturating_sub(symbol.len()).saturating_add(1);
			let next_x = content_x
				.saturating_add(u16::try_from(prefix_width).unwrap_or(u16::MAX))
				.saturating_add(u16::try_from(state.len()).unwrap_or(u16::MAX))
				.saturating_add(2)
				.min(right);
			if !repaint_chrome && cache.label_x != next_x {
				clear_cached_label(frame, cache, row_y, right);
			}
			let next_x = draw_line(frame, content_x, row_y, content_width, &[
				Span::new(prefix.as_str(), state_style),
				Span::new(state, state_style),
				Span::new("  ", panel_ink(FAINT)),
			]);
			cache.prefix_shard = shard;
			cache.prefix_phase = prefix_phase;
			cache.prefix_valid = true;
			next_x
		} else {
			cache.label_x
		};
		let moved = cache.label_x != label_x;
		let label_changed = repaint_chrome
			|| moved
			|| !cache.label_valid
			|| cache.label_shard != shard
			|| cache.label_progress != progress;
		changed |= label_changed;
		if label_changed {
			label_scratch.truncate(0);
			write!(label_scratch, "workspace-{shard:03}.test.ts  [{progress:>3}%]")
				.expect("shard label formatting is infallible");
			let resized = cache.label.len() != label_scratch.len();
			if !repaint_chrome && resized && !moved {
				clear_cached_label(frame, cache, row_y, right);
			}
			let width = right.saturating_sub(label_x);
			if repaint_chrome || moved || resized {
				frame.put_clipped(label_x, row_y, width, label_scratch.as_str(), panel_ink(MUTED));
			} else {
				draw_ascii_changes(
					frame,
					label_x,
					row_y,
					width,
					cache.label.as_str(),
					label_scratch.as_str(),
					panel_ink(MUTED),
				);
			}
			std::mem::swap(&mut cache.label, label_scratch);
			cache.label_shard = shard;
			cache.label_progress = progress;
			cache.label_valid = true;
		}
		cache.label_x = label_x;
	}
	changed
}

fn clear_cached_label(frame: &mut Frame, cache: &LiveRowCache, y: u16, right: u16) {
	if cache.label.is_empty() {
		return;
	}
	let width = u16::try_from(cache.label.len())
		.unwrap_or(u16::MAX)
		.min(right.saturating_sub(cache.label_x));
	frame.fill(Rect::new(cache.label_x, y, width, 1), panel_style());
}

/// Repaints only changed byte runs within an equal-length ASCII label.
fn draw_ascii_changes(
	frame: &mut Frame,
	x: u16,
	y: u16,
	width: u16,
	previous: &str,
	next: &str,
	style: Style,
) {
	if width == 0 || previous == next {
		return;
	}
	if previous.len() != next.len() || !previous.is_ascii() || !next.is_ascii() {
		frame.put_clipped(x, y, width, next, style);
		return;
	}
	let previous = previous.as_bytes();
	let next_bytes = next.as_bytes();
	let limit = previous.len().min(usize::from(width));
	let mut index = 0;
	while index < limit {
		while index < limit && previous[index] == next_bytes[index] {
			index += 1;
		}
		let start = index;
		while index < limit && previous[index] != next_bytes[index] {
			index += 1;
		}
		if start < index {
			let offset = u16::try_from(start).unwrap_or(u16::MAX);
			frame.put_clipped(
				x.saturating_add(offset),
				y,
				u16::try_from(index - start).unwrap_or(u16::MAX),
				&next[start..index],
				style,
			);
		}
	}
}

fn draw_edit_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 8 || rect.height < EDIT_BOX_HEIGHT {
		return;
	}

	let title = [
		Span::new(" Live ", panel_ink(GREEN).bold()),
		Span::new("band · selection semantics ", panel_ink(CYAN)),
	];
	draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	draw_line(frame, rect.x + 2, rect.y + 1, rect.width.saturating_sub(4), &[
		Span::new(charset.check(), panel_ink(GREEN).bold()),
		Span::new(" ", panel_ink(GREEN)),
		Span::new("Transcript selections ride with the text", panel_ink(TEXT)),
	]);
	draw_line(frame, rect.x + 2, rect.y + 2, rect.width.saturating_sub(4), &[Span::new(
		"  margin commits pin the band on kitty-class terminals",
		panel_ink(MUTED),
	)]);
}

/// Paints a submitted message: the prompt gutter, then the rendered
/// Markdown document blitted beside it (or the raw lines when the text
/// isn't renderable as Markdown).
fn draw_submission(frame: &mut Frame, y: u16, submission: &Submission, charset: Charset) {
	if frame.size().width < 4 {
		return;
	}
	let Some(view) = &submission.view else {
		for (offset, line) in submission.text.split('\n').enumerate() {
			let Ok(offset) = u16::try_from(offset) else {
				break;
			};
			let row = y.saturating_add(offset);
			if row >= frame.size().height {
				break;
			}
			let prompt = if offset == 0 { charset.cursor() } else { "  " };
			let text_x = frame.put(1, row, prompt, ink(GREEN).bold());
			let width = frame
				.size()
				.width
				.saturating_sub(1)
				.saturating_sub(text_x.saturating_sub(1));
			draw_submission_text(frame, text_x, row, width, line, charset);
		}
		return;
	};
	frame.put(1, y, charset.cursor(), ink(GREEN).bold());
	frame.blit(view.frame(), 0, view.height(), 3, y);
}
fn explicit_line_count(text: &str) -> u16 {
	u16::try_from(
		text
			.bytes()
			.filter(|byte| *byte == b'\n')
			.count()
			.saturating_add(1),
	)
	.unwrap_or(u16::MAX)
}

/// Paints a rounded panel box through the tier's border glyphs.
fn draw_box(frame: &mut Frame, rect: Rect, border: Style, fill: Style, charset: Charset) {
	if rect.width == 0 || rect.height == 0 {
		return;
	}
	let (tl, tr, _, _, horizontal, vertical) = charset.border(Border::Round);
	frame.fill(rect, fill);
	let mut glyph = [0_u8; 4];
	if rect.width == 1 {
		frame.put(rect.x, rect.y, vertical.encode_utf8(&mut glyph), border);
		return;
	}

	let right = rect.x + rect.width - 1;
	let bottom = rect.y + rect.height - 1;
	frame.put(rect.x, rect.y, tl.encode_utf8(&mut glyph), border);
	frame.put(right, rect.y, tr.encode_utf8(&mut glyph), border);
	for x in rect.x + 1..right {
		frame.put(x, rect.y, horizontal.encode_utf8(&mut glyph), border);
	}

	if rect.height > 1 {
		draw_box_bottom(frame, rect, border, charset);
	}
	for row in rect.y + 1..bottom {
		frame.put(rect.x, row, vertical.encode_utf8(&mut glyph), border);
		frame.put(right, row, vertical.encode_utf8(&mut glyph), border);
	}
}

pub fn underlay(&mut self, rect: Rect, color: Color)

Paints color behind a clipped rectangle: cells still on the terminal’s default background adopt it, cells that named their own keep it. Runs after a subtree paints, so glyph styles — which replace the whole cell — never punch holes in a container’s fill.

pub fn put_image_cell( &mut self, x: u16, y: u16, id: u32, row: u16, col: u16, rows: u16, cols: u16, )

Places one typed Kitty image cell.

pub fn put(&mut self, x: u16, y: u16, text: &str, style: Style) -> u16

Draws printable graphemes until a newline or the right frame edge.

Control characters are ignored. A wide grapheme that would be clipped is omitted rather than leaving a half-cell artifact.

Examples found in repository

examples/chat/demo.rs (line 112)

fn draw_shimmer(
	frame: &mut Frame,
	column: &mut u16,
	start: u16,
	y: u16,
	right: u16,
	text: &str,
	shimmer: Shimmer,
	high: Style,
) {
	for grapheme in xutf::graphemes_str(text) {
		if *column >= right {
			return;
		}
		let style = shimmer.pick(*column - start, ink(FAINT), ink(MUTED), high);
		let next = frame.put(*column, y, grapheme, style);
		if next == *column {
			return;
		}
		*column = next;
	}
}

fn elapsed_label(elapsed: Duration) -> Str {
	let seconds = elapsed.as_secs();
	if seconds < 60 {
		fmts!("{seconds}s")
	} else if seconds < 3_600 {
		fmts!("{}m", seconds / 60)
	} else {
		fmts!("{}h", (seconds / 3_600).min(99))
	}
}

/// The chat demo's slash-command palette. Editor completion is generic;
/// this list is the demo application's own — the `Ctrl+K` command palette
/// surfaces the same entries.
pub fn demo_commands() -> Vec<Command> {
	vec![
		Command::new(
			"security",
			"Plan, run, inspect, import, and compare OMP-native security scans",
			&[],
		)
		.with_args(&[
			("plan", "Draft a scan plan for this workspace", "[focus]"),
			("run", "Execute the current scan plan", ""),
			("inspect", "Browse findings from the last scan", "[finding-id]"),
			("import", "Import an external scan report", "<path>"),
			("compare", "Diff two scan runs", "<run-a> <run-b>"),
		])
		.with_hint("plan|run|inspect|import|compare"),
		Command::new("attach", "Stage an image attachment on the composer", &[]).with_hint("<path>"),
		Command::new("settings", "Open settings menu", &[]),
		Command::new("setup", "Open provider setup", &["providers"]).with_hint("[provider]"),
		Command::new("plan", "Toggle plan mode (agent plans before executing)", &[]),
		Command::new("plan-review", "Re-open the plan review for the latest plan", &[]),
		Command::new("vibe", "Toggle persistent fast worker sessions", &[]),
		Command::new("goal", "Toggle an autonomous objective for this session", &[])
			.with_hint("<objective>"),
		Command::new("guided-goal", "Interview you in chat, then set up goal mode", &[]),
		Command::new("queue", "Queue a message for after the agent yields", &[]),
		Command::new("switch", "Switch model for this session (same as alt+p)", &[]),
		Command::new("fast", "Toggle priority service tier", &[]),
		Command::new("computer", "Toggle the native computer-use tool", &[]),
		Command::new("vision", "Control inspect_image vision delegation", &[]),
		Command::new("prewalk", "Switch to a fast model at the next action", &[]),
		Command::new("advisor", "Toggle the second-model advisor", &[]),
		Command::new("export", "Export session to an HTML file", &[]),
		Command::new("dump", "Copy the session transcript to clipboard", &[]),
		Command::new("share", "Share session via an encrypted link", &[]),
		Command::new("collab", "Share this session live via a relay", &[]),
		Command::new("join", "Join a shared collab session", &[]),
		Command::new("leave", "Leave the collab session", &[]),
		Command::new("browser", "Toggle browser headless vs visible mode", &[]),
		Command::new("copy", "Pick conversation text or code to copy", &[]),
		Command::new("todo", "View or modify the agent's todo list", &[]),
		Command::new("session", "Session management commands", &[]),
		Command::new("jobs", "Show async background jobs status", &[]),
		Command::new("usage", "Show provider usage and limits", &[]),
		Command::new("stats", "Launch the local stats dashboard", &[]),
		Command::new("changelog", "Show changelog entries", &[]),
		Command::new("hotkeys", "Show all keyboard shortcuts", &[]),
		Command::new("tools", "Show tools currently visible to the agent", &[]),
		Command::new("context", "Show estimated context usage breakdown", &[]),
		Command::new("agents", "Open Agent Control Center dashboard", &[]),
		Command::new("branch", "Create a new branch from a previous message", &[]),
		Command::new("fork", "Create a new fork from a previous message", &[]),
		Command::new("tree", "Navigate the session tree", &[]),
		Command::new("login", "Login with an OAuth provider", &[]),
		Command::new("logout", "Logout from an OAuth provider", &[]),
		Command::new("mcp", "Manage MCP servers", &[]),
		Command::new("ssh", "Manage SSH hosts", &[]),
		Command::new("new", "Start a new session", &[]),
		Command::new("fresh", "Reset provider state without changing the transcript", &[]),
		Command::new("clear", "Clear conversation context, keeping the session", &[]),
		Command::new("drop", "Delete the current session and start a new one", &[]),
		Command::new("compact", "Manually compact the session context", &[]),
		Command::new("shake", "Drop heavy content from context", &[]),
		Command::new("handoff", "Hand off context to a new session", &[]),
		Command::new("resume", "Resume a different session", &[]),
		Command::new("btw", "Ask an ephemeral side question", &[]),
		Command::new("tan", "Run a background agent on tangential work", &[]),
		Command::new("omfg", "Forge a rule from a recurring complaint", &[]),
		Command::new("retry", "Retry the last failed agent turn", &[]),
		Command::new("debug", "Open the debug tools selector", &[]),
		Command::new("memory", "Inspect and operate memory maintenance", &[]),
		Command::new("rename", "Rename the current session", &[]),
		Command::new("move", "Move the session to a different directory", &[]),
		Command::new("add-dir", "Add a workspace directory", &[]),
		Command::new("remove-dir", "Remove a workspace directory", &[]),
		Command::new("dirs", "List this session's workspace directories", &[]),
		Command::new("marketplace", "Manage marketplace plugins", &[]),
		Command::new("plugins", "View and manage installed plugins", &[]),
		Command::new("reload-plugins", "Reload skills, commands, hooks, tools, and agents", &[]),
		Command::new("force", "Force the next turn to use a specific tool", &["force:"]),
		Command::new("live", "Start Codex-backed realtime voice mode", &[]),
		Command::new("pause", "Freeze all agents until resumed", &[]),
		Command::new("quit", "Quit the application", &["q"]),
	]
}

/// A submitted message rendered as Markdown (with embedded markup), cached
/// until the text or the content width changes.
struct Submission {
	text:  String,
	width: u16,
	/// `None` when the text can't be a markdown document (a literal
	/// `</md>`, or embedded interactive markup) — painted verbatim instead.
	view:  Option<Ui>,
}

impl Submission {
	fn new(text: String, width: u16, ctx: &UiContext) -> Self {
		let view = Self::view(&text, width, ctx);
		Self { text, width, view }
	}

	fn view(text: &str, width: u16, ctx: &UiContext) -> Option<Ui> {
		(!text.contains("</md>") && next_ref_tag(text).is_none())
			.then(|| Ui::from_markup(format!("<md>{text}</md>"), width, ctx.clone()).ok())
			.flatten()
	}

	fn resize(&mut self, width: u16, ctx: &UiContext) {
		if self.width != width {
			self.width = width;
			self.view = Self::view(&self.text, width, ctx);
		}
	}

	/// Rendered row count, including the fallback's own line count.
	fn height(&self) -> u16 {
		self
			.view
			.as_ref()
			.map_or_else(|| explicit_line_count(&self.text), Ui::height)
	}
}

/// One append-only transcript entry. The log is retained so a geometry
/// rebuild can replay every entry at the new width; between rebuilds each
/// entry is measured and painted exactly once, then never touched again.
enum Entry {
	/// The closed command box that opens the session.
	Command,
	/// The n-th scripted narration message.
	Message(usize),
	/// A finished shard's permanent result line.
	ShardDone(u16),
	/// A message submitted through the composer.
	Submitted(Box<Submission>),
}

/// Demo-specific focused editor leaf with completion and syntax rendering.
struct DemoInput {
	props:   Props,
	slot:    Slot,
	editor:  Rc<RefCell<Editor>>,
	outcome: Rc<RefCell<Option<EditOutcome>>>,
}

impl DemoInput {
	fn new(editor: Rc<RefCell<Editor>>, outcome: Rc<RefCell<Option<EditOutcome>>>) -> Self {
		Self { props: Props::new(), slot: next_slot(), editor, outcome }
	}

	/// Cells before the editor text: the two-cell prompt plus a gap —
	/// identical on every tier.
	const fn input_offset() -> u16 {
		3
	}

	/// The `╰─` composer prompt composed from the tier's round border.
	fn input_prompt(charset: Charset) -> Str {
		let (_, _, bl, _, horizontal, _) = charset.border(Border::Round);
		fmts!("{bl}{horizontal}")
	}

	const fn input_width(width: u16) -> u16 {
		width.saturating_sub(Self::input_offset()).saturating_sub(1)
	}

	fn paint_picker(pc: &mut PaintCtx<'_>, rect: Rect, y: u16, editor: &Editor) {
		let Some(picker) = editor.picker() else {
			return;
		};
		let (start, suggestions) = picker.visible_suggestions();
		let overflow = picker.len() > suggestions.len();
		let row_right = rect
			.x
			.saturating_add(rect.width.saturating_sub(u16::from(overflow)));
		let primary_width = suggestions
			.iter()
			.filter_map(|suggestion| match suggestion.display() {
				SuggestionDisplay::Text(name) => Some(visible_width(name).saturating_add(2)),
				SuggestionDisplay::Emoji { .. } => None,
			})
			.max()
			.unwrap_or(12)
			.clamp(12, 32);

		for (offset, suggestion) in suggestions.iter().enumerate() {
			let Ok(offset) = u16::try_from(offset) else {
				break;
			};
			let row = y.saturating_add(offset);
			if row >= pc.clip {
				break;
			}
			let selected = start + usize::from(offset) == picker.selected();
			let label = if selected { ink(GREEN) } else { ink(TEXT) };
			let description = if selected { ink(GREEN) } else { ink(MUTED) };
			pc.frame.put(
				rect.x,
				row,
				if selected {
					pc.ctx.charset.cursor()
				} else {
					"  "
				},
				label,
			);
			match suggestion.display() {
				SuggestionDisplay::Text(name) => {
					draw_line(
						pc.frame,
						rect.x.saturating_add(2),
						row,
						row_right.saturating_sub(rect.x.saturating_add(2)),
						&[Span::new(name, label)],
					);
					if let Some(text) = suggestion.description()
						&& rect.width > 40
					{
						let description_x = rect
							.x
							.saturating_add(2)
							.saturating_add(primary_width)
							.min(row_right);
						draw_line(
							pc.frame,
							description_x,
							row,
							row_right.saturating_sub(description_x),
							&[Span::new(text, description)],
						);
					}
				},
				SuggestionDisplay::Emoji { emoji, shortcode } => {
					let mut column = pc.frame.put(rect.x.saturating_add(2), row, emoji, label);
					column = pc.frame.put(column, row, "  ", label);
					if shortcode.starts_with(':') {
						pc.frame.put(column, row, shortcode, label);
					} else {
						column = pc.frame.put(column, row, ":", label);
						column = pc.frame.put(column, row, shortcode, label);
						pc.frame.put(column, row, ":", label);
					}
				},
			}
		}

		if overflow && !suggestions.is_empty() {
			let (track, thumb_glyph) = pc.ctx.charset.scrollbar();
			let track_x = rect.x.saturating_add(rect.width.saturating_sub(1));
			for offset in 0..suggestions.len() {
				let Ok(offset) = u16::try_from(offset) else {
					break;
				};
				pc.frame
					.put(track_x, y.saturating_add(offset), track, ink(FAINT));
			}
			let thumb = picker
				.selected()
				.saturating_mul(suggestions.len().saturating_sub(1))
				/ picker.len().saturating_sub(1);
			pc.frame.put(
				track_x,
				y.saturating_add(u16::try_from(thumb).unwrap_or(u16::MAX)),
				thumb_glyph,
				ink(GREEN),
			);
		}
	}
}

impl Component for DemoInput {
	fn props(&self) -> &Props {
		&self.props
	}

	fn props_mut(&mut self) -> &mut Props {
		&mut self.props
	}

	fn slot(&self) -> Slot {
		self.slot
	}

	fn measure(&mut self, _ctx: &UiContext) -> (u16, u16) {
		(6, 40)
	}

	fn height(&mut self, _ctx: &UiContext, width: u16) -> u16 {
		let editor = self.editor.borrow();
		editor
			.input_height_for(Self::input_width(width))
			.saturating_add(editor.picker_height())
	}

	fn paint(&mut self, pc: &mut PaintCtx<'_>, rect: Rect) {
		pc.hits
			.push(Hit { rect, slot: self.slot, tag: HitTag::Press });
		let editor = self.editor.borrow();
		let input_x = rect.x.saturating_add(Self::input_offset());
		let input_width = Self::input_width(rect.width);
		let input_height = editor.input_height_for(input_width);
		let theme = Theme::default();
		let mut in_comment = false;
		for (offset, row) in editor.view(input_width).iter().enumerate() {
			let row_y = rect
				.y
				.saturating_add(u16::try_from(offset).unwrap_or(u16::MAX));
			if row_y >= pc.clip {
				break;
			}
			if offset == 0 {
				pc.frame
					.put(rect.x, row_y, &Self::input_prompt(pc.ctx.charset), ink(FAINT));
			}
			let mut spans: SmallVec<Span<'_>, 16> = SmallVec::new();
			if editor.options().xml {
				let (runs, next) = highlight_xml(row.text, &theme, in_comment);
				in_comment = next;
				push_row_spans(&editor, row.text, &runs, &mut spans);
			} else {
				push_row_spans(&editor, row.text, &[], &mut spans);
			}
			draw_line(pc.frame, input_x, row_y, input_width, &spans);
			if let Some(cursor_column) = row.cursor_column {
				if cursor_column >= visible_width(row.text)
					&& let Some(hint) = editor.inline_hint()
				{
					let hint_x = input_x.saturating_add(cursor_column).saturating_add(1);
					let width = input_width.saturating_sub(cursor_column.saturating_add(1));
					draw_line(pc.frame, hint_x, row_y, width, &[Span::new(
						hint.as_str(),
						ink(MUTED).dim(),
					)]);
				}
				pc.frame.set_cursor(
					input_x
						.saturating_add(cursor_column)
						.min(rect.x.saturating_add(rect.width.saturating_sub(2))),
					row_y,
				);
			}
		}
		Self::paint_picker(pc, rect, rect.y.saturating_add(input_height), &editor);
	}

	fn focusable(&self) -> bool {
		true
	}

	fn key(&mut self, _ec: &mut EventCtx<'_>, key: Key) -> Flow {
		let outcome = self.editor.borrow_mut().handle(key);
		*self.outcome.borrow_mut() = Some(outcome);
		// The editor owns every key while focused. In particular, an ignored
		// picker key must not escape into `Ui`'s focus-ring navigation; the
		// demo applies its quit policy from the recorded `EditOutcome`.
		Flow::Consumed
	}

	fn mouse(
		&mut self,
		_ec: &mut EventCtx<'_>,
		_tag: HitTag,
		at: (u16, u16),
		rect: Rect,
		mouse: Mouse,
	) -> Flow {
		let width = Self::input_width(rect.width);
		match mouse {
			Mouse::Click => {
				self.editor.borrow_mut().set_cursor_visual_row(
					usize::from(at.1.saturating_sub(rect.y)),
					at.0
						.saturating_sub(rect.x.saturating_add(Self::input_offset())),
					width,
				);
				Flow::Consumed
			},
			Mouse::WheelUp | Mouse::WheelDown => {
				let delta = if mouse == Mouse::WheelUp { -1 } else { 1 };
				if self
					.editor
					.borrow()
					.scroll_rows(delta, width, usize::from(rect.height))
				{
					Flow::Consumed
				} else {
					Flow::Skip
				}
			},
			_ => Flow::Skip,
		}
	}

	fn paste(&mut self, _ec: &mut EventCtx<'_>, text: &str) -> Flow {
		if matches!(self.editor.borrow_mut().insert_text(text), EditOutcome::Changed) {
			Flow::Consumed
		} else {
			Flow::Skip
		}
	}
}
/// Whether the demo is working, and how the status bar's brand segment
/// blends between its two states.
struct WorkState {
	working: bool,
	/// When the current mode began; the working timer counts from here.
	since:   Duration,
	/// Brand foreground: [`GREEN`] while working, [`MUTED`] at rest.
	fade:    Tween<Color>,
}

/// Powerline status split into a left brand group — spinner and session
/// timer while working, the omp brand at rest, the foreground tweening
/// between the two so neither swap ever snaps — and a right-docked
/// session group (branch, context, cost). Panes too narrow for both
/// groups fall back to one left-anchored band that sheds from the tail.
struct DemoStatus {
	props:   Props,
	slot:    Slot,
	work:    Rc<RefCell<WorkState>>,
	model:   Rc<RefCell<Str>>,
	charset: Charset,
	right:   Status,
}

impl DemoStatus {
	fn new(work: Rc<RefCell<WorkState>>, model: Rc<RefCell<Str>>, charset: Charset) -> Self {
		let mut props = Props::new();
		props.set(Prop::Id, STATUS_ID);
		let right = Self::right_group(charset);
		Self { props, slot: next_slot(), work, model, charset, right }
	}

	/// One styled band-group shell on the shared dark backdrop.
	fn group() -> Status {
		Status::new()
			.with(Prop::Bg, Color::Rgb(18, 18, 18))
			.with(Prop::Fg, TEXT)
	}

	/// The brand segment at `now`: spinner plus session timer while
	/// working, the omp badge at rest, foreground riding the work fade.
	fn brand_segment(&self, now: Duration) -> Segment {
		let work = self.work.borrow();
		let brand = if work.working {
			fmts!(
				"{} {}",
				self.charset.spinner().at(now),
				elapsed_label(now.saturating_sub(work.since))
			)
		} else {
			fmts!("{} omp", self.charset.icon(Icon::Omp))
		};
		Segment::new()
			.label(brand)
			.with(Prop::Fg, work.fade.sample(now))
	}

	fn model_segment(&self) -> Segment {
		Segment::new()
			.label(fmts!("{} {}", self.charset.icon(Icon::Model), self.model.borrow()))
			.with(Prop::Fg, GREEN)
	}

	fn git_segment(charset: Charset) -> Segment {
		Segment::new()
			.label(fmts!("{} main *5 +9", charset.icon(Icon::Branch)))
			.with(Prop::Fg, CYAN)
	}

	fn context_segment(charset: Charset) -> Segment {
		Segment::new()
			.label(fmts!("{} 39.1%/1M", charset.icon(Icon::Context)))
			.with(Prop::Fg, GOLD)
	}

	fn cost_segment() -> Segment {
		Segment::new()
			.label("$60.07 (sub) + $8.65 (adv)")
			.with(Prop::Fg, PURPLE)
	}

	/// The left band group: brand and model.
	fn left_group(&self, now: Duration) -> Status {
		Self::group()
			.segment(self.brand_segment(now))
			.segment(self.model_segment())
	}

	/// The right band group: branch, context, and cost.
	fn right_group(charset: Charset) -> Status {
		Self::group()
			.with_str(Prop::Align, "right")
			.segment(Self::git_segment(charset))
			.segment(Self::context_segment(charset))
			.segment(Self::cost_segment())
	}

	/// Every segment in one band, for panes too narrow to split.
	fn combined(&self, now: Duration) -> Status {
		Self::group()
			.segment(self.brand_segment(now))
			.segment(self.model_segment())
			.segment(Self::git_segment(self.charset))
			.segment(Self::context_segment(self.charset))
			.segment(Self::cost_segment())
	}
}

impl Component for DemoStatus {
	fn props(&self) -> &Props {
		&self.props
	}

	fn props_mut(&mut self) -> &mut Props {
		&mut self.props
	}

	fn slot(&self) -> Slot {
		self.slot
	}

	fn measure(&mut self, ctx: &UiContext) -> (u16, u16) {
		self.combined(Duration::ZERO).measure(ctx)
	}

	fn height(&mut self, _ctx: &UiContext, _width: u16) -> u16 {
		1
	}

	fn paint(&mut self, pc: &mut PaintCtx<'_>, rect: Rect) {
		let mut left = self.left_group(pc.now);
		let (_, left_width) = left.measure(pc.ctx);
		let (_, right_width) = self.right.measure(pc.ctx);
		if left_width.saturating_add(2).saturating_add(right_width) <= rect.width {
			left.paint(pc, Rect::new(rect.x, rect.y, left_width, 1));
			let dock = rect
				.x
				.saturating_add(rect.width)
				.saturating_sub(right_width);
			self
				.right
				.paint(pc, Rect::new(dock, rect.y, right_width, 1));
		} else {
			let mut combined = self.combined(pc.now);
			combined.paint(pc, rect);
		}
		let work = self.work.borrow();
		let fade_frame = work
			.fade
			.settles_at()
			.min(pc.now.saturating_add(FADE_FRAME));
		let deadline = match (work.working, work.fade.is_settled(pc.now)) {
			(true, true) => Some(pc.ctx.charset.spinner().next_change(pc.now)),
			(true, false) => Some(pc.ctx.charset.spinner().next_change(pc.now).min(fade_frame)),
			(false, false) => Some(fade_frame),
			(false, true) => None,
		};
		if let Some(at) = deadline {
			pc.wake(self.slot, at);
		}
	}

	fn paints_background(&self) -> bool {
		false
	}
}

/// One retained chat document update and its exact repainted row ranges.
pub struct RenderedFrame<'a> {
	pub(crate) frame:       &'a Frame,
	pub(crate) stable_rows: u16,
	pub(crate) damage:      SmallVec<(u16, u16), 4>,
}

/// Produces the animated transcript, work indicator, editor, and status
/// line demo.
pub struct Demo {
	started_at:         Instant,
	/// Detected presentation context shared by every retained subtree.
	ctx:                UiContext,
	/// Cancel hint resolved once through the context's charset.
	cancel_hint:        &'static str,
	editor_ui:          Ui,
	editor:             Rc<RefCell<Editor>>,
	edit_outcome:       Rc<RefCell<Option<EditOutcome>>>,
	work:               Rc<RefCell<WorkState>>,
	last_working:       bool,
	model:              Rc<RefCell<Str>>,
	/// Images staged on the composer, previewed above the status line.
	attachments:        Attachments,
	/// Append-only transcript log, replayed in full on geometry rebuilds.
	transcript:         Vec<Entry>,
	/// Entries already painted into the retained frame.
	drawn_entries:      usize,
	/// Rows covered by the drawn entries; doubles as `stable_rows`.
	transcript_rows:    u16,
	appended_messages:  usize,
	emitted_shards:     u16,
	last_viewport:      Size,
	height_floor:       u16,
	frame:              Frame,
	/// Geometry of the retained live panel chrome.
	live_panel:         Option<Rect>,
	/// Reusable text and placement state for the animated shard rows.
	live_rows:          [LiveRowCache; LIVE_SHARD_ROWS as usize],
	/// One build buffer rotated through the row caches without reallocating.
	live_label_scratch: StrMut,
	/// Columns reserved at the right edge for a composited rail; the
	/// editor and title dock against the remaining visible width.
	right_inset:        u16,
	/// The composer submitted `/switch`; the host opens the model picker.
	switch_requested:   bool,
}

impl Demo {
	/// Starts the demo's animation clock, presenting through the host's
	/// detected context.
	pub fn new(ctx: &UiContext) -> Self {
		let editor = Rc::new(RefCell::new({
			let mut editor = Editor::new(EditorOptions::default());
			editor.set_completion(Box::new(SlashCommands::new(demo_commands())));
			editor
		}));
		let edit_outcome = Rc::new(RefCell::new(None));
		let work = Rc::new(RefCell::new(WorkState {
			working: true,
			since:   Duration::ZERO,
			fade:    Tween::settled(GREEN),
		}));
		let model = Rc::new(RefCell::new(Str::new_static("Fable 5++")));
		let pane = EditorPane::new()
			.input(DemoInput::new(Rc::clone(&editor), Rc::clone(&edit_outcome)))
			.status(DemoStatus::new(Rc::clone(&work), Rc::clone(&model), ctx.charset));
		let attachments = pane.attachments();
		let editor_ui = Ui::from_root(pane, 0, ctx.clone());
		Self {
			started_at: Instant::now(),
			ctx: ctx.clone(),
			cancel_hint: ctx.charset.icon(Icon::Cancellable),
			editor_ui,
			editor,
			edit_outcome,
			work,
			last_working: true,
			model,
			attachments,
			transcript: vec![Entry::Command],
			drawn_entries: 0,
			transcript_rows: 0,
			appended_messages: 0,
			emitted_shards: 0,
			last_viewport: Size::new(0, 0),
			height_floor: 0,
			frame: Frame::new(Size::new(0, 0)),
			live_panel: None,
			live_rows: std::array::from_fn(|_| LiveRowCache::new()),
			live_label_scratch: StrMut::with_capacity(40),
			right_inset: 0,
			switch_requested: false,
		}
	}

	/// Routes a key through the editor and reports whether the demo should
	/// exit. Quit policy lives here, not in the editor: once the editor
	/// reports a key unused, `esc` first cancels running work and only quits
	/// at rest; `ctrl-c` always quits.
	pub fn handle_key(&mut self, key: Key) -> bool {
		*self.edit_outcome.borrow_mut() = None;
		let _ = self.editor_ui.handle_key(key);
		let outcome = self
			.edit_outcome
			.borrow_mut()
			.take()
			.unwrap_or(EditOutcome::Ignored);
		match outcome {
			EditOutcome::Submitted(text) => {
				let trimmed = text.trim();
				if trimmed == "/switch" {
					self.switch_requested = true;
					return false;
				}
				if let Some(path) = trimmed
					.strip_prefix("/attach")
					.filter(|rest| rest.is_empty() || rest.starts_with(' '))
				{
					let path = path.trim().to_string();
					if !path.is_empty() {
						self.attach_image(&path);
					}
					return false;
				}
				let _ = self.attachments.take();
				self.refresh_composer();
				self
					.transcript
					.push(Entry::Submitted(Box::new(Submission::new(
						text,
						Self::message_width(self.last_viewport.width),
						&self.ctx,
					))));
				self.set_working(true, self.started_at.elapsed());
				false
			},
			EditOutcome::Changed => {
				self.reconcile_attachments();
				false
			},
			EditOutcome::Ignored => {
				if key == Key::Ctrl('c') {
					return true;
				}
				if key != Key::Esc {
					return false;
				}
				if self.work.borrow().working {
					self.set_working(false, self.started_at.elapsed());
					return false;
				}
				true
			},
		}
	}

	/// Consumes a pending `/switch` request submitted through the composer.
	pub fn take_switch_request(&mut self) -> bool {
		std::mem::take(&mut self.switch_requested)
	}

	/// Routes a document-space mouse report into the editor UI.
	pub fn handle_mouse(&mut self, report: &MouseReport) {
		let editor_height = self.editor_ui.height();
		let editor_y = self.frame.size().height.saturating_sub(editor_height);
		let editor_bottom = editor_y.saturating_add(editor_height);
		if report.row < editor_y || report.row >= editor_bottom {
			return;
		}
		let _ = self
			.editor_ui
			.handle_mouse(report.col, report.row - editor_y, report.kind);
	}

	/// Switches the work state and retargets the brand fade. The status bar
	/// repaints immediately and the fade departs from whatever color is on
	/// screen, so rapid cancel/resume never snaps.
	fn set_working(&mut self, working: bool, now: Duration) {
		{
			let mut work = self.work.borrow_mut();
			if work.working == working {
				return;
			}
			work.working = working;
			work.since = now;
			let target = if working { GREEN } else { MUTED };
			work
				.fade
				.retarget(now, target, BRAND_FADE, Easing::EaseInOut);
		}
		self.editor_ui.invalidate(STATUS_ID);
	}

	/// Reflects a session model switch in the status bar's model segment.
	pub fn set_model(&mut self, name: &str) {
		*self.model.borrow_mut() = Str::from(name);
		self.editor_ui.invalidate(STATUS_ID);
	}

	/// Routes sanitized bracketed paste text through the editor. Dropped
	/// paths to existing image files (quoted, escaped, `file://`, or
	/// multi-file) and any large paste collapse into composer attachment
	/// chips instead of raw text.
	pub fn handle_paste(&mut self, text: &str) {
		let paths = omp_tui::paste::dropped_paths(text);
		if !paths.is_empty()
			&& paths.iter().all(|path| {
				omp_tui::paste::is_image_path(path) && std::path::Path::new(path.as_str()).is_file()
			}) {
			for path in &paths {
				self.attach_image(path);
			}
			return;
		}
		if text.lines().count() > 10 || text.len() > 1000 {
			self.attach_paste(text);
			return;
		}
		let _ = self.editor_ui.handle_paste(text);
	}

	/// Routes Ctrl+Shift+V clipboard text into the composer verbatim: no
	/// attachment staging, no large-paste collapse — the text stays inline
	/// and editable.
	pub fn handle_paste_raw(&mut self, text: &str) {
		let _ = self.editor_ui.handle_paste_raw(text);
	}

	/// Stages `path` on the composer and mentions it in the prompt as an
	/// atomic `<icon> #N` chip expanding to `<ref image=N/>` on submit.
	fn attach_image(&mut self, path: &str) {
		let attachment = self.attachments.push_image(path);
		let payload = format!("<ref image={}/>", attachment.marker);
		self.insert_chip(&attachment, &payload);
	}

	/// Collapses a large paste into a staged attachment card and an atomic
	/// composer chip expanding back to the pasted text on submit.
	fn attach_paste(&mut self, text: &str) {
		let attachment = self.attachments.push_text(text);
		self.insert_chip(&attachment, text);
	}

	/// Inserts one attachment chip as an atomic editor reference.
	fn insert_chip(&mut self, attachment: &Attachment, payload: &str) {
		let chip = chip_label(attachment, self.ctx.charset);
		{
			let mut editor = self.editor.borrow_mut();
			let _ = editor.insert_reference(&chip, payload);
			let _ = editor.insert_text(" ");
		}
		self.refresh_composer();
	}

	/// Hides staged attachments whose chip the user deleted from the
	/// composer (and re-shows them after an undo). Presence is derived
	/// from the buffer's atomic ranges, never from text matching.
	fn reconcile_attachments(&mut self) {
		let charset = self.ctx.charset;
		let changed = {
			let editor = self.editor.borrow();
			let text = editor.text();
			let ranges = editor.atom_ranges();
			self.attachments.set_visible(|attachment| {
				let chip = chip_label(attachment, charset);
				ranges
					.iter()
					.any(|&(start, end)| text.get(start..end) == Some(chip.as_str()))
			})
		};
		if changed {
			self.refresh_composer();
		}
	}

	/// Relayouts the composer after out-of-band state changed its height.
	fn refresh_composer(&mut self) {
		let width = self.editor_ui.frame().size().width;
		if width > 0 {
			self.editor_ui.resize(width);
		}
	}

	/// Reserves `cols` at the right edge for a composited rail, so the
	/// composer's right-docked chrome stays visible beside it. The next
	/// render relayouts the editor at the narrowed width.
	pub const fn set_right_inset(&mut self, cols: u16) {
		self.right_inset = cols;
	}

	/// The width the composer may actually occupy at `viewport`.
	fn composer_width(&self, viewport: Size) -> u16 {
		viewport.width.saturating_sub(self.right_inset).max(1)
	}

	/// Updates the retained logical document and reports its repainted rows.
	pub fn render(&mut self, viewport: Size) -> RenderedFrame<'_> {
		self.render_at(viewport, self.started_at.elapsed())
	}

	fn render_at(&mut self, viewport: Size, elapsed: Duration) -> RenderedFrame<'_> {
		if viewport.width == 0 || viewport.height == 0 {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			self.live_panel = None;
			self.frame = Frame::new(viewport);
			return RenderedFrame {
				frame:       &self.frame,
				stable_rows: 0,
				damage:      SmallVec::new(),
			};
		}
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		// Fires due animation wakes (the status bar's spinner and brand
		// fade) so the blit below picks up fresh retained pixels.
		self.editor_ui.tick(elapsed);
		let editor_changed = self.editor_ui.take_frame_damage();

		// A viewport change starts a fresh renderer session: replay the
		// whole transcript log at the new width. Between rebuilds the log
		// is append-only and every drawn row is final, so selections over
		// transcript text stay anchored to it in every terminal.
		let rebuild = self.last_viewport != viewport;
		if rebuild {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			let message_width = Self::message_width(viewport.width);
			for entry in &mut self.transcript {
				if let Entry::Submitted(submission) = entry {
					submission.resize(message_width, &self.ctx);
				}
			}
		}
		while self.appended_messages < Self::visible_messages(elapsed) {
			self.transcript.push(Entry::Message(self.appended_messages));
			self.appended_messages += 1;
		}
		while self.emitted_shards < Self::finished_shards(elapsed) {
			self.emitted_shards += 1;
			self.transcript.push(Entry::ShardDone(self.emitted_shards));
		}

		let mut new_rows = 0_u16;
		for entry in &self.transcript[self.drawn_entries..] {
			new_rows = new_rows.saturating_add(Self::entry_height(entry, viewport.width, &self.ctx));
		}
		let transcript_rows = self.transcript_rows.saturating_add(new_rows);
		let editor_height = self.editor_ui.height();
		// Native scrollback is append-only, so the logical document may
		// never shrink while the seam is live: band rows that close again
		// (extra input lines) become blank padding that heals as the
		// transcript grows.
		let natural_height = transcript_rows.saturating_add(Self::band_height(editor_height));
		self.height_floor = self.height_floor.max(natural_height);
		let document_height = self.height_floor.max(viewport.height);
		let transcript_damage_start = if rebuild { 0 } else { self.transcript_rows };
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_y = document_height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		let panel = Rect::new(margin, panel_y, content_width, panel_height);
		let repaint_suffix = rebuild || new_rows > 0 || self.live_panel != Some(panel);
		if rebuild {
			self.frame = Frame::new(Size::new(viewport.width, document_height));
		} else {
			self.frame.resize_height(document_height, base_style());
		}
		if repaint_suffix {
			self.frame.fill(
				Rect::new(
					0,
					transcript_damage_start,
					viewport.width,
					document_height.saturating_sub(transcript_damage_start),
				),
				base_style(),
			);
		}

		// Paint the new transcript entries; rows above `transcript_rows`
		// are final and never repainted.
		let mut y = self.transcript_rows;
		for index in self.drawn_entries..self.transcript.len() {
			let used = self.draw_entry_at(index, y, viewport.width);
			y = y.saturating_add(used);
		}
		self.drawn_entries = self.transcript.len();
		self.transcript_rows = y;

		// The live band repaints in place at the bottom of the document.
		let animation_frame = Self::animation_frame(elapsed);
		let panel_changed = draw_live_panel(
			&mut self.frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			panel,
			repaint_suffix,
			self.emitted_shards,
			animation_frame,
			self.ctx.charset,
		);
		let working = self.work.borrow().working;
		let working_changed = self.last_working != working;
		if !repaint_suffix && self.last_working && !working {
			self
				.frame
				.fill(Rect::new(0, working_y, viewport.width, 1), base_style());
		}
		if working {
			Self::draw_working(&mut self.frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut self.frame, title_y, self.right_inset);
		if repaint_suffix || editor_changed {
			self
				.frame
				.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);
		}
		let mut damage = SmallVec::new();
		if repaint_suffix {
			damage.push((transcript_damage_start, document_height));
		} else {
			if panel_changed {
				damage.push((panel_y, panel_y.saturating_add(panel_height)));
			}
			if working || working_changed {
				damage.push((working_y, working_y.saturating_add(1)));
			}
			if editor_changed {
				damage.push((editor_y, document_height));
			}
		}
		self.last_working = working;
		self.live_panel = Some(panel);

		RenderedFrame { frame: &self.frame, stable_rows: self.transcript_rows, damage }
	}

	fn generation(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / EMIT_INTERVAL.as_millis()).unwrap_or(u64::MAX)
	}

	fn animation_frame(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / 80).unwrap_or(u64::MAX)
	}

	fn visible_messages(elapsed: Duration) -> usize {
		let interval = MESSAGE_INTERVAL.as_millis();
		usize::try_from(elapsed.as_millis() / interval + 1)
			.unwrap_or(usize::MAX)
			.min(4)
	}

	/// Shards whose permanent result line has been appended by `elapsed`:
	/// two per emit tick, capped well inside `u16` document heights.
	fn finished_shards(elapsed: Duration) -> u16 {
		u16::try_from(Self::generation(elapsed).saturating_mul(2).min(60_000))
			.expect("finished shard count is clamped")
	}

	/// Rows the bottom live band occupies: the shard panel, a blank
	/// separator, the activity row, the title air row, and the editor
	/// block.
	const fn band_height(editor_height: u16) -> u16 {
		LIVE_SHARD_ROWS + 2 + 3 + editor_height
	}

	/// Rows `entry` will occupy at `width`, including its trailing blank.
	fn entry_height(entry: &Entry, width: u16, ctx: &UiContext) -> u16 {
		match entry {
			Entry::Command => 5,
			Entry::Message(message) => {
				let mut scratch = Frame::new(Size::new(width, 48));
				Self::draw_message(&mut scratch, 0, *message, width, ctx.charset)
			},
			Entry::ShardDone(_) => 1,
			Entry::Submitted(submission) => submission.height().saturating_add(1),
		}
	}

	const fn message_width(width: u16) -> u16 {
		let narrowed = width.saturating_sub(3);
		if narrowed == 0 { 1 } else { narrowed }
	}

	/// Paints one transcript entry at `y` and returns the rows it used.
	fn draw_entry_at(&mut self, index: usize, y: u16, width: u16) -> u16 {
		Self::draw_entry(&mut self.frame, &self.transcript[index], y, width, &self.ctx)
	}

	/// Paints `entry` into any frame at `y` and returns the rows it used,
	/// including the trailing blank.
	fn draw_entry(frame: &mut Frame, entry: &Entry, y: u16, width: u16, ctx: &UiContext) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		match entry {
			Entry::Command => {
				draw_command_box(frame, Rect::new(margin, y, content_width, 4), ctx.charset);
				5
			},
			Entry::Message(message) => Self::draw_message(frame, y, *message, width, ctx.charset),
			Entry::ShardDone(shard) => {
				Self::draw_shard_done(frame, y, *shard, width, ctx.charset);
				1
			},
			Entry::Submitted(submission) => {
				draw_submission(frame, y, submission, ctx.charset);
				submission.height().saturating_add(1)
			},
		}
	}

	/// Composes exactly one viewport of throwaway resize-drag content at the
	/// new geometry: the live band anchors to the bottom, then transcript
	/// entries are walked backward and rewrapped at `viewport.width` until
	/// the screen is full — O(viewport) work per drag frame, with the
	/// topmost entry sliced when it only partially fits. Retained transcript
	/// state is untouched, so the settle rebuild replays full history
	/// exactly once.
	pub fn render_resize_preview(&mut self, viewport: Size) -> Frame {
		let elapsed = self.started_at.elapsed();
		let mut frame = Frame::new(viewport);
		if viewport.width == 0 || viewport.height == 0 {
			return frame;
		}
		frame.fill(Rect::new(0, 0, viewport.width, viewport.height), base_style());
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		self.editor_ui.tick(elapsed);

		// The live band, laid out exactly like the retained document's.
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_height = self.editor_ui.height();
		let editor_y = viewport.height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		draw_live_panel(
			&mut frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			Rect::new(margin, panel_y, content_width, panel_height),
			true,
			self.emitted_shards,
			Self::animation_frame(elapsed),
			self.ctx.charset,
		);
		if self.work.borrow().working {
			Self::draw_working(&mut frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut frame, title_y, self.right_inset);
		frame.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);

		// Transcript tail, bottom-up above the band.
		let mut remaining = panel_y;
		for entry in self.transcript.iter().rev() {
			if remaining == 0 {
				break;
			}
			let height = Self::entry_height(entry, viewport.width, &self.ctx);
			if height == 0 {
				continue;
			}
			if height <= remaining {
				remaining -= height;
				Self::draw_entry(&mut frame, entry, remaining, viewport.width, &self.ctx);
			} else {
				// Slice the bottom rows of the partially visible entry.
				let mut scratch = Frame::new(Size::new(viewport.width, height));
				scratch.fill(Rect::new(0, 0, viewport.width, height), base_style());
				Self::draw_entry(&mut scratch, entry, 0, viewport.width, &self.ctx);
				frame.blit(&scratch, height - remaining, remaining, 0, 0);
				remaining = 0;
			}
		}
		frame
	}

	/// Paints the n-th scripted message and returns rows used including
	/// the trailing blank. Measurement draws into a scratch frame.
	fn draw_message(frame: &mut Frame, y: u16, message: usize, width: u16, charset: Charset) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		if message == 2 {
			draw_edit_box(frame, Rect::new(margin, y, content_width, EDIT_BOX_HEIGHT), charset);
			return EDIT_BOX_HEIGHT + 1;
		}
		let bottom = frame.size().height;
		let spans = Self::message_spans(message);
		// Prose flows edge-to-edge grapheme-exact — no side pads — so every
		// wrapped row re-joins byte-for-byte in native selection.
		let used = draw_flowed(frame, Rect::new(0, y, width, bottom.saturating_sub(y)), &spans);
		used.saturating_add(1)
	}

	fn message_spans(message: usize) -> SmallVec<Span<'static>, 3> {
		let mut spans = SmallVec::new();
		match message {
			0 => {
				spans.push(Span::new("Transcript rows are ", prose_style()));
				spans.push(Span::new("append-only", code_style()));
				spans.push(Span::new(
					": every line is painted once, becomes stable, and rides into native scrollback \
					 with any selection anchored to it.",
					prose_style(),
				));
			},
			1 => {
				spans.push(Span::new(
					"Only the bottom band repaints in place — the live shard panel, the activity \
					 shimmer, and the composer. Rows above it are never rewritten.",
					prose_style(),
				));
			},
			_ => {
				spans.push(Span::new(
					"On terminals that move margin-scrolled rows into scrollback, commits scroll only \
					 the stable transcript through a ",
					prose_style(),
				));
				spans.push(Span::new("DECSTBM top region", code_style()));
				spans.push(Span::new(", so the live band never shifts on screen.", prose_style()));
			},
		}
		spans
	}

	/// Appends a finished shard's permanent one-line result.
	fn draw_shard_done(frame: &mut Frame, y: u16, shard: u16, width: u16, charset: Charset) {
		let margin = u16::from(width >= 50);
		let prefix = fmts!(" {} shard {shard:03} passed", charset.check());
		let detail = fmts!("  workspace-{shard:03}.test.ts  [100%]");
		draw_line(frame, margin + 1, y, width.saturating_sub(margin * 2).saturating_sub(2), &[
			Span::new(prefix.as_str(), ink(GREEN)),
			Span::new(detail.as_str(), ink(MUTED)),
		]);
	}

	/// Shimmering activity line above the editor. The spinner and timer
	/// live in the status bar's brand segment; this row only narrates.
	fn draw_working(frame: &mut Frame, y: u16, elapsed: Duration, hint: &str) {
		if y >= frame.size().height || frame.size().width < 4 {
			return;
		}
		let start = u16::from(frame.size().width >= 50);
		let mut column = start;
		let length = xutf::graphemes_str(WORKING_MESSAGE)
			.count()
			.saturating_add(xutf::graphemes_str(hint).count())
			.saturating_add(1);
		let length = u16::try_from(length).unwrap_or(u16::MAX);
		let shimmer = Shimmer::new(elapsed, SHIMMER_PERIOD, length);
		let right = frame.size().width.saturating_sub(1);
		draw_shimmer(frame, &mut column, start, y, right, hint, shimmer, ink(CYAN));
		draw_shimmer(frame, &mut column, start, y, right, " ", shimmer, ink(GREEN));
		draw_shimmer(frame, &mut column, start, y, right, WORKING_MESSAGE, shimmer, ink(GREEN));
	}

	/// The session title resting right-aligned in the air row between
	/// the working narration and the status band — against the visible
	/// right bound, inside any rail reservation — so the gap reads as
	/// session identity instead of dead space.
	fn draw_session_title(frame: &mut Frame, y: u16, right_inset: u16) {
		let width = frame.size().width.saturating_sub(right_inset);
		let title_width = visible_width(SESSION_TITLE);
		if y >= frame.size().height || width < title_width.saturating_add(2) {
			return;
		}
		let x = width.saturating_sub(title_width.saturating_add(1));
		draw_line(frame, x, y, title_width, &[Span::new(SESSION_TITLE, ink(FAINT).italic())]);
	}
}

/// The closed four-row command box that opens the transcript.
fn draw_command_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 4 || rect.height < 4 {
		return;
	}

	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	let header = [
		Span::new(" PARALLEL TEST RUN ", panel_ink(GREEN).bold()),
		Span::new("results append below · live rows in the bottom panel", panel_ink(MUTED)),
	];
	draw_line(frame, content_x, rect.y + 1, content_width, &header);
	let command = [
		Span::new("$ ", panel_ink(MUTED)),
		Span::new("bun test --parallel=8", panel_ink(CYAN)),
		Span::new(" --timeout=30000 --all-workspaces", panel_ink(TEXT)),
	];
	draw_line(frame, content_x, rect.y + 2, content_width, &command);
}

/// The live band's shard panel: twelve mutable rows that repaint in place
/// every frame and never enter native scrollback.
fn draw_live_panel(
	frame: &mut Frame,
	rows: &mut [LiveRowCache; LIVE_SHARD_ROWS as usize],
	label_scratch: &mut StrMut,
	rect: Rect,
	repaint_chrome: bool,
	emitted_shards: u16,
	animation_frame: u64,
	charset: Charset,
) -> bool {
	let mut changed = repaint_chrome;
	if repaint_chrome {
		draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	}
	if rect.width < 4 || rect.height < 3 {
		return changed;
	}

	if repaint_chrome {
		let title = [
			Span::new(" LIVE SHARDS ", panel_ink(GREEN).bold()),
			Span::new("mutable rows repaint in place ", panel_ink(MUTED)),
		];
		draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	}
	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	for row in 0..rect.height.saturating_sub(2) {
		let shard = emitted_shards.saturating_add(row).saturating_add(1);
		let phase = (u64::from(row) + animation_frame) % 11;
		let (prefix_phase, symbol, state, state_style, progress) = match phase {
			0 => (
				0,
				"⠼",
				"running",
				panel_ink(GREEN).bold(),
				(u64::from(row) * 17 + animation_frame * 7) % 100,
			),
			1..=7 => {
				(1, "·", "working", panel_ink(MUTED), (u64::from(row) * 17 + animation_frame * 7) % 100)
			},
			_ => (2, "·", "queued ", panel_ink(FAINT), 0),
		};
		let row_y = rect.y + 1 + row;
		let right = content_x
			.saturating_add(content_width)
			.min(frame.size().width);
		let cache = &mut rows[usize::from(row)];
		let prefix_changed = repaint_chrome
			|| !cache.prefix_valid
			|| cache.prefix_shard != shard
			|| cache.prefix_phase != prefix_phase;
		changed |= prefix_changed;
		let label_x = if prefix_changed {
			let prefix = fmts!(" {symbol} shard {shard:03} ");
			let prefix_width = prefix.len().saturating_sub(symbol.len()).saturating_add(1);
			let next_x = content_x
				.saturating_add(u16::try_from(prefix_width).unwrap_or(u16::MAX))
				.saturating_add(u16::try_from(state.len()).unwrap_or(u16::MAX))
				.saturating_add(2)
				.min(right);
			if !repaint_chrome && cache.label_x != next_x {
				clear_cached_label(frame, cache, row_y, right);
			}
			let next_x = draw_line(frame, content_x, row_y, content_width, &[
				Span::new(prefix.as_str(), state_style),
				Span::new(state, state_style),
				Span::new("  ", panel_ink(FAINT)),
			]);
			cache.prefix_shard = shard;
			cache.prefix_phase = prefix_phase;
			cache.prefix_valid = true;
			next_x
		} else {
			cache.label_x
		};
		let moved = cache.label_x != label_x;
		let label_changed = repaint_chrome
			|| moved
			|| !cache.label_valid
			|| cache.label_shard != shard
			|| cache.label_progress != progress;
		changed |= label_changed;
		if label_changed {
			label_scratch.truncate(0);
			write!(label_scratch, "workspace-{shard:03}.test.ts  [{progress:>3}%]")
				.expect("shard label formatting is infallible");
			let resized = cache.label.len() != label_scratch.len();
			if !repaint_chrome && resized && !moved {
				clear_cached_label(frame, cache, row_y, right);
			}
			let width = right.saturating_sub(label_x);
			if repaint_chrome || moved || resized {
				frame.put_clipped(label_x, row_y, width, label_scratch.as_str(), panel_ink(MUTED));
			} else {
				draw_ascii_changes(
					frame,
					label_x,
					row_y,
					width,
					cache.label.as_str(),
					label_scratch.as_str(),
					panel_ink(MUTED),
				);
			}
			std::mem::swap(&mut cache.label, label_scratch);
			cache.label_shard = shard;
			cache.label_progress = progress;
			cache.label_valid = true;
		}
		cache.label_x = label_x;
	}
	changed
}

fn clear_cached_label(frame: &mut Frame, cache: &LiveRowCache, y: u16, right: u16) {
	if cache.label.is_empty() {
		return;
	}
	let width = u16::try_from(cache.label.len())
		.unwrap_or(u16::MAX)
		.min(right.saturating_sub(cache.label_x));
	frame.fill(Rect::new(cache.label_x, y, width, 1), panel_style());
}

/// Repaints only changed byte runs within an equal-length ASCII label.
fn draw_ascii_changes(
	frame: &mut Frame,
	x: u16,
	y: u16,
	width: u16,
	previous: &str,
	next: &str,
	style: Style,
) {
	if width == 0 || previous == next {
		return;
	}
	if previous.len() != next.len() || !previous.is_ascii() || !next.is_ascii() {
		frame.put_clipped(x, y, width, next, style);
		return;
	}
	let previous = previous.as_bytes();
	let next_bytes = next.as_bytes();
	let limit = previous.len().min(usize::from(width));
	let mut index = 0;
	while index < limit {
		while index < limit && previous[index] == next_bytes[index] {
			index += 1;
		}
		let start = index;
		while index < limit && previous[index] != next_bytes[index] {
			index += 1;
		}
		if start < index {
			let offset = u16::try_from(start).unwrap_or(u16::MAX);
			frame.put_clipped(
				x.saturating_add(offset),
				y,
				u16::try_from(index - start).unwrap_or(u16::MAX),
				&next[start..index],
				style,
			);
		}
	}
}

fn draw_edit_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 8 || rect.height < EDIT_BOX_HEIGHT {
		return;
	}

	let title = [
		Span::new(" Live ", panel_ink(GREEN).bold()),
		Span::new("band · selection semantics ", panel_ink(CYAN)),
	];
	draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	draw_line(frame, rect.x + 2, rect.y + 1, rect.width.saturating_sub(4), &[
		Span::new(charset.check(), panel_ink(GREEN).bold()),
		Span::new(" ", panel_ink(GREEN)),
		Span::new("Transcript selections ride with the text", panel_ink(TEXT)),
	]);
	draw_line(frame, rect.x + 2, rect.y + 2, rect.width.saturating_sub(4), &[Span::new(
		"  margin commits pin the band on kitty-class terminals",
		panel_ink(MUTED),
	)]);
}

/// Paints a submitted message: the prompt gutter, then the rendered
/// Markdown document blitted beside it (or the raw lines when the text
/// isn't renderable as Markdown).
fn draw_submission(frame: &mut Frame, y: u16, submission: &Submission, charset: Charset) {
	if frame.size().width < 4 {
		return;
	}
	let Some(view) = &submission.view else {
		for (offset, line) in submission.text.split('\n').enumerate() {
			let Ok(offset) = u16::try_from(offset) else {
				break;
			};
			let row = y.saturating_add(offset);
			if row >= frame.size().height {
				break;
			}
			let prompt = if offset == 0 { charset.cursor() } else { "  " };
			let text_x = frame.put(1, row, prompt, ink(GREEN).bold());
			let width = frame
				.size()
				.width
				.saturating_sub(1)
				.saturating_sub(text_x.saturating_sub(1));
			draw_submission_text(frame, text_x, row, width, line, charset);
		}
		return;
	};
	frame.put(1, y, charset.cursor(), ink(GREEN).bold());
	frame.blit(view.frame(), 0, view.height(), 3, y);
}
fn explicit_line_count(text: &str) -> u16 {
	u16::try_from(
		text
			.bytes()
			.filter(|byte| *byte == b'\n')
			.count()
			.saturating_add(1),
	)
	.unwrap_or(u16::MAX)
}

/// Paints a rounded panel box through the tier's border glyphs.
fn draw_box(frame: &mut Frame, rect: Rect, border: Style, fill: Style, charset: Charset) {
	if rect.width == 0 || rect.height == 0 {
		return;
	}
	let (tl, tr, _, _, horizontal, vertical) = charset.border(Border::Round);
	frame.fill(rect, fill);
	let mut glyph = [0_u8; 4];
	if rect.width == 1 {
		frame.put(rect.x, rect.y, vertical.encode_utf8(&mut glyph), border);
		return;
	}

	let right = rect.x + rect.width - 1;
	let bottom = rect.y + rect.height - 1;
	frame.put(rect.x, rect.y, tl.encode_utf8(&mut glyph), border);
	frame.put(right, rect.y, tr.encode_utf8(&mut glyph), border);
	for x in rect.x + 1..right {
		frame.put(x, rect.y, horizontal.encode_utf8(&mut glyph), border);
	}

	if rect.height > 1 {
		draw_box_bottom(frame, rect, border, charset);
	}
	for row in rect.y + 1..bottom {
		frame.put(rect.x, row, vertical.encode_utf8(&mut glyph), border);
		frame.put(right, row, vertical.encode_utf8(&mut glyph), border);
	}
}

fn draw_box_bottom(frame: &mut Frame, rect: Rect, border: Style, charset: Charset) {
	if rect.width < 2 || rect.height < 2 {
		return;
	}
	let (_, _, bl, br, horizontal, _) = charset.border(Border::Round);
	let mut glyph = [0_u8; 4];
	let right = rect.x + rect.width - 1;
	let bottom = rect.y + rect.height - 1;
	frame.put(rect.x, bottom, bl.encode_utf8(&mut glyph), border);
	frame.put(right, bottom, br.encode_utf8(&mut glyph), border);
	for x in rect.x + 1..right {
		frame.put(x, bottom, horizontal.encode_utf8(&mut glyph), border);
	}
}

fn draw_line(frame: &mut Frame, x: u16, y: u16, width: u16, spans: &[Span<'_>]) -> u16 {
	let right = x.saturating_add(width).min(frame.size().width);
	let mut column = x;
	for span in spans {
		column = frame.put_clipped(column, y, right.saturating_sub(column), span.text, span.style);
		if column >= right {
			break;
		}
	}
	column
}

/// Flows `spans` grapheme-exact across the rect like a bare terminal,
/// preserving all whitespace and flagging each exactly-filled row boundary
/// soft so native selection copies the paragraph as one unbroken line.
/// Returns the rows used.
fn draw_flowed(frame: &mut Frame, rect: Rect, spans: &[Span<'_>]) -> u16 {
	if rect.width == 0 || rect.height == 0 {
		return 0;
	}
	let full_row = rect.x == 0 && rect.width == frame.size().width;
	let mut row = 0_u16;
	let mut column = 0_u16;
	let mut drew_anything = false;

	for span in spans {
		for grapheme in xutf::graphemes_str(span.text) {
			let grapheme_width = visible_width(grapheme);
			if grapheme_width == 0 || grapheme_width > rect.width {
				continue;
			}
			if column.saturating_add(grapheme_width) > rect.width {
				// Only an exactly-filled row is byte-joinable by autowrap.
				if full_row && column == rect.width {
					frame.set_soft_wrap(rect.y.saturating_add(row));
				}
				row += 1;
				column = 0;
			}
			if row >= rect.height {
				return rect.height;
			}
			frame.put(rect.x + column, rect.y + row, grapheme, span.style);
			column += grapheme_width;
			drew_anything = true;
		}
	}

	if drew_anything { row + 1 } else { 0 }
}

examples/footers.rs (line 207)

fn compose(scene: &Scene) -> Frame {
	let height = STUDIES
		.iter()
		.map(|study| study.rows + 3)
		.fold(3_u16, u16::saturating_add);
	let mut frame = Frame::new(Size::new(scene.width, height));
	frame.fill(Rect::new(0, 0, scene.width, height), ink(TEXT));

	let column = frame.put(1, 0, "composer footer studies", ink(TEXT).bold());
	frame.put(
		column.saturating_add(2),
		0,
		"split + air gap, six session-title placements",
		ink(MUTED),
	);
	frame.put(1, 1, "↑/↓ scroll · PgUp/PgDn page · Home/End jump · q quits", ink(FAINT));

	let mut y = 3_u16;
	for (index, study) in STUDIES.iter().enumerate() {
		let number = fmts!("{:>2} ", index + 1);
		let mut column = frame.put(1, y, &number, ink(GOLD).bold());
		column = frame.put(column, y, study.title, ink(TEXT).bold());
		column = frame.put(column, y, "  ", ink(FAINT));
		frame.put(column, y, study.note, ink(MUTED));
		(study.draw)(&mut frame, y + 1, scene);
		y = y.saturating_add(study.rows + 3);
	}
	frame
}

// ── studies ─────────────────────────────────────────────────────────────────

/// 1: the pi layout verbatim — a bordered composer whose top border
/// carries the session band on the left and the title on the right, with
/// the spinner narrating intent on its own row above the box.
fn study_pi_parity(frame: &mut Frame, y: u16, scene: &Scene) {
	draw_working_spin(frame, 1, y, scene);
	let (tl, tr, bl, br, horizontal, vertical) = border_glyphs(scene.charset);
	let right = scene.right_edge();
	draw_border_row(frame, y + 1, scene, tl, tr, horizontal);
	let segments = [model(scene), omp_brand(scene), git(scene), context(scene), cost()];
	draw_band(frame, 2, y + 1, scene, &segments);
	let band_end = 2_u16.saturating_add(band_width(scene, &segments));
	draw_border_title(frame, y + 1, scene, band_end.saturating_add(2));
	frame.put(0, y + 2, vertical, ink(FAINT));
	frame.put(2, y + 2, beam(scene.charset), ink(TEXT));
	frame.put(right, y + 2, vertical, ink(FAINT));
	draw_border_row(frame, y + 3, scene, bl, br, horizontal);
}

/// 2: split + air gap as picked, with the title moving into the air row
/// so the breathing space doubles as identity.
fn study_gap_title(frame: &mut Frame, y: u16, scene: &Scene) {
	draw_working(frame, 1, y, scene);
	let title = fit_title(scene, scene.width.saturating_sub(2));
	let x = scene
		.width
		.saturating_sub(width_of(&title).saturating_add(1));
	frame.put(x, y + 1, &title, ink(FAINT).italic());
	draw_split_bands(frame, y + 2, scene);
	draw_input(frame, 0, y + 3, scene);
}

/// 3: the title joins the left band beside the brand segment, so the
/// band row itself answers "what session is this"; session facts keep
/// the right cap.
fn study_band_title(frame: &mut Frame, y: u16, scene: &Scene) {
	draw_working(frame, 1, y, scene);
	let right = [model(scene), git(scene), context(scene), Seg::new(COST_SHORT, PURPLE)];
	let right_width = band_width(scene, &right);
	let brand_seg = brand(scene);
	let (_, separator, _) = band_chrome(scene.charset);
	let fixed = band_width(scene, std::slice::from_ref(&brand_seg))
		.saturating_add(width_of(separator).saturating_add(2));
	let budget = scene
		.width
		.saturating_sub(right_width.saturating_add(2))
		.saturating_sub(fixed);
	let left = [brand_seg, Seg::new(fit_title(scene, budget), TEXT)];
	draw_band(frame, 0, y + 2, scene, &left);
	draw_band(frame, scene.width.saturating_sub(right_width), y + 2, scene, &right);
	draw_input(frame, 0, y + 3, scene);
}

/// 4: split + air untouched; the title borrows the prompt row's right
/// edge and would yield to long input lines.
fn study_prompt_title(frame: &mut Frame, y: u16, scene: &Scene) {
	draw_working(frame, 1, y, scene);
	draw_split_bands(frame, y + 2, scene);
	draw_input(frame, 0, y + 3, scene);
	let title = fit_title(scene, scene.width.saturating_sub(8));
	let x = scene
		.width
		.saturating_sub(width_of(&title).saturating_add(1));
	frame.put(x, y + 3, &title, ink(FAINT).italic());
}

/// 5: the title gets its own dim row above the narration, heading the
/// whole live block like a section title.
fn study_crown(frame: &mut Frame, y: u16, scene: &Scene) {
	let title = fit_title(scene, scene.width.saturating_sub(2));
	frame.put(1, y, &title, ink(MUTED).bold());
	draw_working(frame, 1, y + 1, scene);
	draw_split_bands(frame, y + 3, scene);
	draw_input(frame, 0, y + 4, scene);
}

/// 6: a bordered composer again, but the title takes the top border and
/// the band moves into the bottom hem, so chrome frames the input from
/// both sides.
fn study_hem(frame: &mut Frame, y: u16, scene: &Scene) {
	draw_working(frame, 1, y, scene);
	let (tl, tr, bl, br, horizontal, vertical) = border_glyphs(scene.charset);
	let right = scene.right_edge();
	draw_border_row(frame, y + 1, scene, tl, tr, horizontal);
	draw_border_title(frame, y + 1, scene, 4);
	frame.put(0, y + 2, vertical, ink(FAINT));
	frame.put(2, y + 2, beam(scene.charset), ink(TEXT));
	frame.put(right, y + 2, vertical, ink(FAINT));
	draw_border_row(frame, y + 3, scene, bl, br, horizontal);
	draw_band(frame, 2, y + 3, scene, &full_band(scene));
}

// ── shared chrome ───────────────────────────────────────────────────────────

/// One status item: a label painted in its identity color.
struct Seg {
	label: Str,
	color: Color,
}

impl Seg {
	fn new(label: impl Into<Str>, color: Color) -> Self {
		Self { label: label.into(), color }
	}
}

fn brand(scene: &Scene) -> Seg {
	Seg::new(fmts!("{} {}", scene.spinner(), scene.timer()), GREEN)
}

fn omp_brand(scene: &Scene) -> Seg {
	Seg::new(fmts!("{} omp", scene.charset.icon(Icon::Omp)), MUTED)
}

fn model(scene: &Scene) -> Seg {
	Seg::new(fmts!("{} {MODEL}", scene.charset.icon(Icon::Model)), GREEN)
}

fn git(scene: &Scene) -> Seg {
	Seg::new(fmts!("{} {GIT}", scene.charset.icon(Icon::Branch)), CYAN)
}

fn context(scene: &Scene) -> Seg {
	Seg::new(fmts!("{} {CONTEXT}", scene.charset.icon(Icon::Context)), GOLD)
}

fn cost() -> Seg {
	Seg::new(Str::new_static(COST), PURPLE)
}

fn full_band(scene: &Scene) -> [Seg; 5] {
	[brand(scene), model(scene), git(scene), context(scene), cost()]
}

/// The picked split arrangement: brand caps left, session caps right.
fn draw_split_bands(frame: &mut Frame, y: u16, scene: &Scene) {
	let left = [brand(scene), model(scene)];
	let right = [git(scene), context(scene), cost()];
	draw_band(frame, 0, y, scene, &left);
	let x = scene.width.saturating_sub(band_width(scene, &right));
	draw_band(frame, x, y, scene, &right);
}

/// Status-band chrome per tier, mirroring the `<status>` component.
const fn band_chrome(charset: Charset) -> (&'static str, &'static str, &'static str) {
	match charset {
		Charset::Ascii => ("", ">", ">"),
		Charset::Unicode => ("", "›", "›"),
		Charset::NerdFont => ("\u{e0b6}", "\u{e0b1}", "\u{e0b0}"),
	}
}

const fn border_glyphs(
	charset: Charset,
) -> (&'static str, &'static str, &'static str, &'static str, &'static str, &'static str) {
	match charset {
		Charset::Ascii => ("+", "+", "+", "+", "-", "|"),
		_ => ("╭", "╮", "╰", "╯", "─", "│"),
	}
}

const fn beam(charset: Charset) -> &'static str {
	match charset {
		Charset::Ascii => "_",
		_ => "▏",
	}
}

const fn ink(color: Color) -> Style {
	Style::new().fg(color)
}

fn width_of(text: &str) -> u16 {
	u16::try_from(xutf::width_str(text)).unwrap_or(u16::MAX)
}

/// [`TITLE`] truncated to at most `max` cells, ellipsized when it cannot
/// fit whole.
fn fit_title(scene: &Scene, max: u16) -> Str {
	if width_of(TITLE) <= max {
		return Str::new_static(TITLE);
	}
	let ellipsis = match scene.charset {
		Charset::Ascii => "...",
		_ => "…",
	};
	let budget = max.saturating_sub(width_of(ellipsis));
	let mut used = 0_u16;
	let mut end = 0_usize;
	for grapheme in xutf::graphemes_str(TITLE) {
		let cells = width_of(grapheme);
		if used.saturating_add(cells) > budget {
			break;
		}
		used = used.saturating_add(cells);
		end += grapheme.len();
	}
	if end == 0 {
		return Str::default();
	}
	fmts!("{}{ellipsis}", TITLE[..end].trim_end())
}

/// Total cells a powerline band with `segments` occupies, mirroring the
/// `<status>` component's measurement.
fn band_width(scene: &Scene, segments: &[Seg]) -> u16 {
	let (left_cap, separator, right_cap) = band_chrome(scene.charset);
	let text = segments
		.iter()
		.map(|segment| width_of(&segment.label))
		.fold(0_u16, u16::saturating_add);
	let separators = u16::try_from(segments.len().saturating_sub(1))
		.unwrap_or(u16::MAX)
		.saturating_mul(width_of(separator).saturating_add(2));
	text
		.saturating_add(separators)
		.saturating_add(width_of(left_cap))
		.saturating_add(2)
		.saturating_add(width_of(right_cap))
}

/// Paints a powerline band at `x`: cap, padded segments, cap.
fn draw_band(frame: &mut Frame, x: u16, y: u16, scene: &Scene, segments: &[Seg]) {
	let (left_cap, separator, right_cap) = band_chrome(scene.charset);
	let base = Style::new().fg(TEXT).bg(BAND_BG);
	let edge = ink(BAND_BG);
	let mut column = frame.put(x, y, left_cap, edge);
	column = frame.put(column, y, " ", base);
	for (index, segment) in segments.iter().enumerate() {
		if index > 0 {
			column = frame.put(column, y, " ", base.dim());
			column = frame.put(column, y, separator, base.dim());
			column = frame.put(column, y, " ", base.dim());
		}
		column = frame.put(column, y, &segment.label, base.fg(segment.color));
	}
	column = frame.put(column, y, " ", base);
	frame.put(column, y, right_cap, edge);
}

/// A full-width horizontal border row: corner, rule fill, corner.
fn draw_border_row(
	frame: &mut Frame,
	y: u16,
	scene: &Scene,
	left: &str,
	right: &str,
	horizontal: &str,
) {
	let edge = scene.right_edge();
	let mut column = frame.put(0, y, left, ink(FAINT));
	while column < edge {
		column = frame.put(column, y, horizontal, ink(FAINT));
	}
	frame.put(edge, y, right, ink(FAINT));
}

/// Right-aligns ` TITLE ` into an already-painted border row, keeping two
/// rule cells before the corner and truncating against `min_x`.
fn draw_border_title(frame: &mut Frame, y: u16, scene: &Scene, min_x: u16) {
	let slot_end = scene.right_edge().saturating_sub(2);
	let title = fit_title(scene, slot_end.saturating_sub(min_x).saturating_sub(2));
	if title.is_empty() {
		return;
	}
	let x = slot_end.saturating_sub(width_of(&title).saturating_add(2));
	let column = frame.put(x, y, " ", ink(FAINT));
	let column = frame.put(column, y, &title, ink(TEXT));
	frame.put(column, y, " ", ink(FAINT));
}

/// The shimmering working line: cancel hint, then the narration, riding
/// one crest sweep exactly like the chat demo's activity row.
fn draw_working(frame: &mut Frame, x: u16, y: u16, scene: &Scene) {
	let hint = scene.charset.icon(Icon::Cancellable);
	let length = width_of(hint)
		.saturating_add(1)
		.saturating_add(width_of(WORKING));
	let shimmer = Shimmer::new(scene.elapsed, SHIMMER_PERIOD, length);
	let mut column = x;
	draw_shimmer(frame, &mut column, x, y, scene.right_edge(), hint, shimmer, ink(CYAN));
	draw_shimmer(frame, &mut column, x, y, scene.right_edge(), " ", shimmer, ink(GREEN));
	draw_shimmer(frame, &mut column, x, y, scene.right_edge(), WORKING, shimmer, ink(GREEN));
}

/// The pi flavor of the working line: the spinner and timer lead, then
/// the shimmering narration — the band below carries no brand segment.
fn draw_working_spin(frame: &mut Frame, x: u16, y: u16, scene: &Scene) {
	let mut column = frame.put(x, y, scene.spinner(), ink(GREEN));
	column = frame.put(column, y, " ", ink(GREEN));
	column = frame.put(column, y, &scene.timer(), ink(MUTED));
	column = frame.put(column, y, " ", ink(MUTED));
	let shimmer = Shimmer::new(scene.elapsed, SHIMMER_PERIOD, width_of(WORKING));
	let start = column;
	draw_shimmer(frame, &mut column, start, y, scene.right_edge(), WORKING, shimmer, ink(GREEN));
}

/// Paints `text` under the crest, advancing `column`; `start` anchors
/// cell zero so every segment rides one sweep.
#[allow(clippy::too_many_arguments, reason = "immediate-mode painter threading frame state")]
fn draw_shimmer(
	frame: &mut Frame,
	column: &mut u16,
	start: u16,
	y: u16,
	right: u16,
	text: &str,
	shimmer: Shimmer,
	high: Style,
) {
	for grapheme in xutf::graphemes_str(text) {
		if *column >= right {
			return;
		}
		let style = shimmer.pick(*column - start, ink(FAINT), ink(MUTED), high);
		let next = frame.put(*column, y, grapheme, style);
		if next == *column {
			return;
		}
		*column = next;
	}
}

/// The composer prompt row: corner, then the idle cursor beam.
fn draw_input(frame: &mut Frame, x: u16, y: u16, scene: &Scene) {
	let prompt = match scene.charset {
		Charset::Ascii => "+-",
		_ => "╰─",
	};
	let column = frame.put(x, y, prompt, ink(FAINT));
	frame.put(column.saturating_add(1), y, beam(scene.charset), ink(TEXT));
}

examples/chat/welcome.rs (line 281)

	fn draw_backdrop(&mut self, viewport: Size, clock: Duration, elapsed: f32) {
		let interval = ambient_interval(clock, BACKDROP_IDLE_INTERVAL);
		if self
			.backdrop_at
			.is_none_or(|rendered_at| clock.saturating_sub(rendered_at) >= interval)
		{
			let fade = smooth((elapsed / BACKDROP_FADE).clamp(0.0, 1.0));
			self
				.backdrop_frame
				.fill(Rect::new(0, 0, viewport.width, viewport.height), Style::default());
			let frame = &mut self.backdrop_frame;
			let mut buffer = [0_u8; 4];
			let dim = |color: Color| Color::Rgb(0, 0, 0).lerp(color, fade);
			self.surface.render(
				&mut self.backdrop,
				clock,
				viewport.width,
				viewport.height,
				|x, y, glyph, fg, bg| {
					let style = Style::new().fg(dim(fg));
					let style = match bg {
						Some(bg) => style.bg(dim(bg)),
						None => style,
					};
					frame.put(x, y, glyph.encode_utf8(&mut buffer), style);
				},
			);
			self.backdrop_at = Some(clock);
		}
		self.frame.clone_from(&self.backdrop_frame);
	}

	fn draw_card(&mut self, cols: u16, left: u16, top: u16, elapsed: f32, hover: f32) {
		let full = cols == CARD_COLS;
		let logo_left = if full {
			left + 3
		} else {
			left + (cols - LOGO_COLS as u16) / 2
		};
		self.logo_origin = (logo_left, top + 2);
		// Pointer-tracking border glow: the brand gradient sampled by angle
		// around the card center (the disk's own palette), strongest near
		// the pointer, scaled by the eased hover amount.
		let pointer = self.pointer;
		let center =
			(f32::from(left) + f32::from(cols) / 2.0, f32::from(top) + f32::from(CARD_ROWS) / 2.0);
		let edge_at = move |x: u16, y: u16| -> Style {
			let Some((px, py)) = pointer.filter(|_| hover > 0.02) else {
				return on_card(CARD_BORDER);
			};
			let dx = (f32::from(x) - f32::from(px)) * 0.5;
			let dy = f32::from(y) - f32::from(py);
			let glow = hover * (-(dx * dx + dy * dy) / 34.0).exp();
			if glow < 0.02 {
				return on_card(CARD_BORDER);
			}
			let angle = (f32::from(y) - center.1).atan2((f32::from(x) - center.0) * 0.5);
			let brand = vec3_color(gradient(angle - elapsed * 0.5));
			on_card(CARD_BORDER.lerp(brand, glow))
		};
		let frame = &mut self.frame;
		frame.fill(Rect::new(left, top, cols, CARD_ROWS), on_card(TEXT));

		let right = left + cols - 1;
		let bottom = top + CARD_ROWS - 1;
		let divider = bottom - 2;
		let (tl, tr, bl, br, horizontal, vertical) = self.charset.border(Border::Round);
		let grid = self.charset.grid();
		let mut glyph = [0_u8; 4];
		frame.put(left, top, tl.encode_utf8(&mut glyph), edge_at(left, top));
		frame.put(right, top, tr.encode_utf8(&mut glyph), edge_at(right, top));
		frame.put(left, divider, grid.middle.0.encode_utf8(&mut glyph), edge_at(left, divider));
		frame.put(right, divider, grid.middle.2.encode_utf8(&mut glyph), edge_at(right, divider));
		frame.put(left, bottom, bl.encode_utf8(&mut glyph), edge_at(left, bottom));
		frame.put(right, bottom, br.encode_utf8(&mut glyph), edge_at(right, bottom));
		for x in left + 1..right {
			frame.put(x, top, horizontal.encode_utf8(&mut glyph), edge_at(x, top));
			frame.put(x, divider, horizontal.encode_utf8(&mut glyph), edge_at(x, divider));
			frame.put(x, bottom, horizontal.encode_utf8(&mut glyph), edge_at(x, bottom));
		}
		for y in top + 1..bottom {
			if y != divider {
				frame.put(left, y, vertical.encode_utf8(&mut glyph), edge_at(left, y));
				frame.put(right, y, vertical.encode_utf8(&mut glyph), edge_at(right, y));
			}
		}

		frame.put(left + 2, top, self.title.as_str(), on_card(TEXT_STRONG));
		if full {
			frame.put(left + 34, top, " SESSION ORBIT ", on_card(FAINT));
			draw_dust(frame, left, top, elapsed);
			draw_sessions(frame, left, top, self.charset);
			draw_beam(frame, left, top, elapsed);
		}

		blit_logo(frame, &self.logo, logo_left, top + 2, CARD_BG);

		let footer = divider + 1;
		frame.fill(Rect::new(left + 1, footer, cols - 2, 1), on_footer(TEXT));
		if full {
			frame.put(left + 3, divider, " SHORTCUTS ", on_card(FAINT));
			let dot = fmts!(" {} ", self.charset.icon(Icon::Enabled));
			let x = frame.put(left + cols - 21, top, &dot, on_card(GREEN));
			frame.put(x, top, "rust-analyzer ", on_card(MUTED));
			draw_full_hints(frame, left, footer);
		} else {
			draw_smol_hints(frame, left, cols, footer);
		}
	}
}

impl Default for Welcome {
	fn default() -> Self {
		Self::new(Charset::NerdFont)
	}
}

fn draw_dust(frame: &mut Frame, left: u16, top: u16, elapsed: f32) {
	for &(x, y, offset) in &DUST {
		let pulse = 0.5 + 0.5 * (elapsed * 1.4 + offset).sin();
		let color = FAINT.lerp(CYAN, pulse * 0.28);
		frame.put(left + x, top + y, "·", on_card(color));
	}
	frame.put(left + 1, top + 7, HORIZON, on_card(FAINT.lerp(INDIGO, 0.16)));
	frame.put(left + 14, top + 1, "+Z", on_card(FAINT));
}

fn draw_beam(frame: &mut Frame, left: u16, top: u16, elapsed: f32) {
	let phase = (elapsed * 9.0) as usize % BEAM.len();
	for (index, &(x, y, glyph)) in BEAM.iter().enumerate() {
		let direct = index.abs_diff(phase);
		let distance = direct.min(BEAM.len() - direct);
		let color = match distance {
			0 => TEXT_STRONG,
			1 => CYAN,
			_ => FAINT.lerp(INDIGO, 0.34),
		};
		frame.put(left + x, top + y, glyph, on_card(color));
	}
}

fn draw_sessions(frame: &mut Frame, left: u16, top: u16, charset: Charset) {
	let (_, _, _, _, _, vertical) = charset.border(Border::Round);
	let mut glyph = [0_u8; 4];
	let panel_x = left + 36;
	frame.put(panel_x, top + 2, "RECENT SESSIONS", on_card(MUTED));
	frame.put(left + CARD_COLS - 14, top + 2, "4 / LOCAL", on_card(FAINT));
	for y in top + 4..=top + 10 {
		frame.put(panel_x, y, vertical.encode_utf8(&mut glyph), on_card(FAINT.lerp(INDIGO, 0.18)));
	}
	for (index, (label, age)) in SESSIONS.iter().enumerate() {
		let y = top + 4 + index as u16 * 2;
		if index == 0 {
			frame.fill(Rect::new(panel_x - 2, y, CARD_COLS - 35, 1), on_selected(TEXT));
			frame.put(panel_x - 2, y, charset.rail(), on_selected(GREEN));
			frame.put(panel_x, y, charset.radio(true), on_selected(GREEN));
			frame.put(panel_x + 2, y, age, on_selected(GREEN));
			frame.put(panel_x + 7, y, label, on_selected(TEXT_STRONG));
		} else {
			frame.put(panel_x, y, charset.radio(false), on_card(FAINT));
			frame.put(panel_x + 2, y, age, on_card(FAINT));
			frame.put(panel_x + 7, y, label, on_card(MUTED));
		}
	}
}

fn draw_full_hints(frame: &mut Frame, left: u16, y: u16) {
	frame.put(left + 3, y, "#", on_footer(CYAN));
	frame.put(left + 5, y, "actions", on_footer(MUTED));
	frame.put(left + 14, y, "/", on_footer(GREEN));
	frame.put(left + 16, y, "commands", on_footer(MUTED));
	frame.put(left + 27, y, "!", on_footer(AMBER));
	frame.put(left + 29, y, "shell", on_footer(MUTED));
	frame.put(left + 37, y, "$", on_footer(VIOLET));
	frame.put(left + 39, y, "python", on_footer(MUTED));
	frame.put(left + CARD_COLS - 23, y, "↑↓ move", on_footer(FAINT));
	frame.put(left + CARD_COLS - 13, y, "↵ resume", on_footer(TEXT_STRONG));
}

fn draw_smol_hints(frame: &mut Frame, left: u16, cols: u16, y: u16) {
	frame.put(left + 3, y, "#", on_footer(CYAN).bold());
	frame.put(left + 5, y, "/", on_footer(CYAN).bold());
	frame.put(left + 7, y, "!", on_footer(AMBER).bold());
	frame.put(left + 9, y, "$", on_footer(GREEN).bold());
	frame.put(left + cols - 14, y, "enter", on_footer(FAINT));
	frame.put(left + cols - 8, y, "resume", on_footer(TEXT_STRONG).bold());
}

fn blit_logo(frame: &mut Frame, logo: &LogoGrid, left: u16, top: u16, background: Color) {
	let mut buffer = [0_u8; 4];
	for (row, cells) in logo.iter().enumerate() {
		for (column, cell) in cells.iter().enumerate() {
			let Some((glyph, color)) = cell else { continue };
			let style = Style::new().fg(*color).bg(background);
			frame.put(left + column as u16, top + row as u16, glyph.encode_utf8(&mut buffer), style);
		}
	}
}

pub fn put_clipped( &mut self, x: u16, y: u16, width: u16, text: &str, style: Style, ) -> u16

Draws printable graphemes within width cells.

The cell bound is also clipped to the frame edge. A wide grapheme that crosses either bound is omitted rather than leaving a half-cell artifact.

Examples found in repository

examples/chat/demo.rs (line 1505)

fn draw_live_panel(
	frame: &mut Frame,
	rows: &mut [LiveRowCache; LIVE_SHARD_ROWS as usize],
	label_scratch: &mut StrMut,
	rect: Rect,
	repaint_chrome: bool,
	emitted_shards: u16,
	animation_frame: u64,
	charset: Charset,
) -> bool {
	let mut changed = repaint_chrome;
	if repaint_chrome {
		draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	}
	if rect.width < 4 || rect.height < 3 {
		return changed;
	}

	if repaint_chrome {
		let title = [
			Span::new(" LIVE SHARDS ", panel_ink(GREEN).bold()),
			Span::new("mutable rows repaint in place ", panel_ink(MUTED)),
		];
		draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	}
	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	for row in 0..rect.height.saturating_sub(2) {
		let shard = emitted_shards.saturating_add(row).saturating_add(1);
		let phase = (u64::from(row) + animation_frame) % 11;
		let (prefix_phase, symbol, state, state_style, progress) = match phase {
			0 => (
				0,
				"⠼",
				"running",
				panel_ink(GREEN).bold(),
				(u64::from(row) * 17 + animation_frame * 7) % 100,
			),
			1..=7 => {
				(1, "·", "working", panel_ink(MUTED), (u64::from(row) * 17 + animation_frame * 7) % 100)
			},
			_ => (2, "·", "queued ", panel_ink(FAINT), 0),
		};
		let row_y = rect.y + 1 + row;
		let right = content_x
			.saturating_add(content_width)
			.min(frame.size().width);
		let cache = &mut rows[usize::from(row)];
		let prefix_changed = repaint_chrome
			|| !cache.prefix_valid
			|| cache.prefix_shard != shard
			|| cache.prefix_phase != prefix_phase;
		changed |= prefix_changed;
		let label_x = if prefix_changed {
			let prefix = fmts!(" {symbol} shard {shard:03} ");
			let prefix_width = prefix.len().saturating_sub(symbol.len()).saturating_add(1);
			let next_x = content_x
				.saturating_add(u16::try_from(prefix_width).unwrap_or(u16::MAX))
				.saturating_add(u16::try_from(state.len()).unwrap_or(u16::MAX))
				.saturating_add(2)
				.min(right);
			if !repaint_chrome && cache.label_x != next_x {
				clear_cached_label(frame, cache, row_y, right);
			}
			let next_x = draw_line(frame, content_x, row_y, content_width, &[
				Span::new(prefix.as_str(), state_style),
				Span::new(state, state_style),
				Span::new("  ", panel_ink(FAINT)),
			]);
			cache.prefix_shard = shard;
			cache.prefix_phase = prefix_phase;
			cache.prefix_valid = true;
			next_x
		} else {
			cache.label_x
		};
		let moved = cache.label_x != label_x;
		let label_changed = repaint_chrome
			|| moved
			|| !cache.label_valid
			|| cache.label_shard != shard
			|| cache.label_progress != progress;
		changed |= label_changed;
		if label_changed {
			label_scratch.truncate(0);
			write!(label_scratch, "workspace-{shard:03}.test.ts  [{progress:>3}%]")
				.expect("shard label formatting is infallible");
			let resized = cache.label.len() != label_scratch.len();
			if !repaint_chrome && resized && !moved {
				clear_cached_label(frame, cache, row_y, right);
			}
			let width = right.saturating_sub(label_x);
			if repaint_chrome || moved || resized {
				frame.put_clipped(label_x, row_y, width, label_scratch.as_str(), panel_ink(MUTED));
			} else {
				draw_ascii_changes(
					frame,
					label_x,
					row_y,
					width,
					cache.label.as_str(),
					label_scratch.as_str(),
					panel_ink(MUTED),
				);
			}
			std::mem::swap(&mut cache.label, label_scratch);
			cache.label_shard = shard;
			cache.label_progress = progress;
			cache.label_valid = true;
		}
		cache.label_x = label_x;
	}
	changed
}

fn clear_cached_label(frame: &mut Frame, cache: &LiveRowCache, y: u16, right: u16) {
	if cache.label.is_empty() {
		return;
	}
	let width = u16::try_from(cache.label.len())
		.unwrap_or(u16::MAX)
		.min(right.saturating_sub(cache.label_x));
	frame.fill(Rect::new(cache.label_x, y, width, 1), panel_style());
}

/// Repaints only changed byte runs within an equal-length ASCII label.
fn draw_ascii_changes(
	frame: &mut Frame,
	x: u16,
	y: u16,
	width: u16,
	previous: &str,
	next: &str,
	style: Style,
) {
	if width == 0 || previous == next {
		return;
	}
	if previous.len() != next.len() || !previous.is_ascii() || !next.is_ascii() {
		frame.put_clipped(x, y, width, next, style);
		return;
	}
	let previous = previous.as_bytes();
	let next_bytes = next.as_bytes();
	let limit = previous.len().min(usize::from(width));
	let mut index = 0;
	while index < limit {
		while index < limit && previous[index] == next_bytes[index] {
			index += 1;
		}
		let start = index;
		while index < limit && previous[index] != next_bytes[index] {
			index += 1;
		}
		if start < index {
			let offset = u16::try_from(start).unwrap_or(u16::MAX);
			frame.put_clipped(
				x.saturating_add(offset),
				y,
				u16::try_from(index - start).unwrap_or(u16::MAX),
				&next[start..index],
				style,
			);
		}
	}
}

fn draw_edit_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 8 || rect.height < EDIT_BOX_HEIGHT {
		return;
	}

	let title = [
		Span::new(" Live ", panel_ink(GREEN).bold()),
		Span::new("band · selection semantics ", panel_ink(CYAN)),
	];
	draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	draw_line(frame, rect.x + 2, rect.y + 1, rect.width.saturating_sub(4), &[
		Span::new(charset.check(), panel_ink(GREEN).bold()),
		Span::new(" ", panel_ink(GREEN)),
		Span::new("Transcript selections ride with the text", panel_ink(TEXT)),
	]);
	draw_line(frame, rect.x + 2, rect.y + 2, rect.width.saturating_sub(4), &[Span::new(
		"  margin commits pin the band on kitty-class terminals",
		panel_ink(MUTED),
	)]);
}

/// Paints a submitted message: the prompt gutter, then the rendered
/// Markdown document blitted beside it (or the raw lines when the text
/// isn't renderable as Markdown).
fn draw_submission(frame: &mut Frame, y: u16, submission: &Submission, charset: Charset) {
	if frame.size().width < 4 {
		return;
	}
	let Some(view) = &submission.view else {
		for (offset, line) in submission.text.split('\n').enumerate() {
			let Ok(offset) = u16::try_from(offset) else {
				break;
			};
			let row = y.saturating_add(offset);
			if row >= frame.size().height {
				break;
			}
			let prompt = if offset == 0 { charset.cursor() } else { "  " };
			let text_x = frame.put(1, row, prompt, ink(GREEN).bold());
			let width = frame
				.size()
				.width
				.saturating_sub(1)
				.saturating_sub(text_x.saturating_sub(1));
			draw_submission_text(frame, text_x, row, width, line, charset);
		}
		return;
	};
	frame.put(1, y, charset.cursor(), ink(GREEN).bold());
	frame.blit(view.frame(), 0, view.height(), 3, y);
}
fn explicit_line_count(text: &str) -> u16 {
	u16::try_from(
		text
			.bytes()
			.filter(|byte| *byte == b'\n')
			.count()
			.saturating_add(1),
	)
	.unwrap_or(u16::MAX)
}

/// Paints a rounded panel box through the tier's border glyphs.
fn draw_box(frame: &mut Frame, rect: Rect, border: Style, fill: Style, charset: Charset) {
	if rect.width == 0 || rect.height == 0 {
		return;
	}
	let (tl, tr, _, _, horizontal, vertical) = charset.border(Border::Round);
	frame.fill(rect, fill);
	let mut glyph = [0_u8; 4];
	if rect.width == 1 {
		frame.put(rect.x, rect.y, vertical.encode_utf8(&mut glyph), border);
		return;
	}

	let right = rect.x + rect.width - 1;
	let bottom = rect.y + rect.height - 1;
	frame.put(rect.x, rect.y, tl.encode_utf8(&mut glyph), border);
	frame.put(right, rect.y, tr.encode_utf8(&mut glyph), border);
	for x in rect.x + 1..right {
		frame.put(x, rect.y, horizontal.encode_utf8(&mut glyph), border);
	}

	if rect.height > 1 {
		draw_box_bottom(frame, rect, border, charset);
	}
	for row in rect.y + 1..bottom {
		frame.put(rect.x, row, vertical.encode_utf8(&mut glyph), border);
		frame.put(right, row, vertical.encode_utf8(&mut glyph), border);
	}
}

fn draw_box_bottom(frame: &mut Frame, rect: Rect, border: Style, charset: Charset) {
	if rect.width < 2 || rect.height < 2 {
		return;
	}
	let (_, _, bl, br, horizontal, _) = charset.border(Border::Round);
	let mut glyph = [0_u8; 4];
	let right = rect.x + rect.width - 1;
	let bottom = rect.y + rect.height - 1;
	frame.put(rect.x, bottom, bl.encode_utf8(&mut glyph), border);
	frame.put(right, bottom, br.encode_utf8(&mut glyph), border);
	for x in rect.x + 1..right {
		frame.put(x, bottom, horizontal.encode_utf8(&mut glyph), border);
	}
}

fn draw_line(frame: &mut Frame, x: u16, y: u16, width: u16, spans: &[Span<'_>]) -> u16 {
	let right = x.saturating_add(width).min(frame.size().width);
	let mut column = x;
	for span in spans {
		column = frame.put_clipped(column, y, right.saturating_sub(column), span.text, span.style);
		if column >= right {
			break;
		}
	}
	column
}

pub fn blit( &mut self, src: &Self, src_top: u16, rows: u16, dst_x: u16, dst_y: u16, )

Copies a cell region from src into this frame — the scroll viewport blit, and the way an embedder composites a sub-document (e.g. a crate::Ui-rendered message) into a hand-painted frame. src rows [src_top, src_top + rows) land at (dst_x, dst_y), clipped to both frames. Wide glyphs whose lead cell falls outside the copied span degrade to blanks rather than leaving orphan continuations. A cursor set on src inside the copied region is translated into this frame’s coordinates; outside it, this frame’s cursor is kept.

Examples found in repository

examples/footers.rs (line 119)

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/demo.rs (line 1127)

	fn render_at(&mut self, viewport: Size, elapsed: Duration) -> RenderedFrame<'_> {
		if viewport.width == 0 || viewport.height == 0 {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			self.live_panel = None;
			self.frame = Frame::new(viewport);
			return RenderedFrame {
				frame:       &self.frame,
				stable_rows: 0,
				damage:      SmallVec::new(),
			};
		}
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		// Fires due animation wakes (the status bar's spinner and brand
		// fade) so the blit below picks up fresh retained pixels.
		self.editor_ui.tick(elapsed);
		let editor_changed = self.editor_ui.take_frame_damage();

		// A viewport change starts a fresh renderer session: replay the
		// whole transcript log at the new width. Between rebuilds the log
		// is append-only and every drawn row is final, so selections over
		// transcript text stay anchored to it in every terminal.
		let rebuild = self.last_viewport != viewport;
		if rebuild {
			self.last_viewport = viewport;
			self.height_floor = 0;
			self.drawn_entries = 0;
			self.transcript_rows = 0;
			let message_width = Self::message_width(viewport.width);
			for entry in &mut self.transcript {
				if let Entry::Submitted(submission) = entry {
					submission.resize(message_width, &self.ctx);
				}
			}
		}
		while self.appended_messages < Self::visible_messages(elapsed) {
			self.transcript.push(Entry::Message(self.appended_messages));
			self.appended_messages += 1;
		}
		while self.emitted_shards < Self::finished_shards(elapsed) {
			self.emitted_shards += 1;
			self.transcript.push(Entry::ShardDone(self.emitted_shards));
		}

		let mut new_rows = 0_u16;
		for entry in &self.transcript[self.drawn_entries..] {
			new_rows = new_rows.saturating_add(Self::entry_height(entry, viewport.width, &self.ctx));
		}
		let transcript_rows = self.transcript_rows.saturating_add(new_rows);
		let editor_height = self.editor_ui.height();
		// Native scrollback is append-only, so the logical document may
		// never shrink while the seam is live: band rows that close again
		// (extra input lines) become blank padding that heals as the
		// transcript grows.
		let natural_height = transcript_rows.saturating_add(Self::band_height(editor_height));
		self.height_floor = self.height_floor.max(natural_height);
		let document_height = self.height_floor.max(viewport.height);
		let transcript_damage_start = if rebuild { 0 } else { self.transcript_rows };
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_y = document_height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		let panel = Rect::new(margin, panel_y, content_width, panel_height);
		let repaint_suffix = rebuild || new_rows > 0 || self.live_panel != Some(panel);
		if rebuild {
			self.frame = Frame::new(Size::new(viewport.width, document_height));
		} else {
			self.frame.resize_height(document_height, base_style());
		}
		if repaint_suffix {
			self.frame.fill(
				Rect::new(
					0,
					transcript_damage_start,
					viewport.width,
					document_height.saturating_sub(transcript_damage_start),
				),
				base_style(),
			);
		}

		// Paint the new transcript entries; rows above `transcript_rows`
		// are final and never repainted.
		let mut y = self.transcript_rows;
		for index in self.drawn_entries..self.transcript.len() {
			let used = self.draw_entry_at(index, y, viewport.width);
			y = y.saturating_add(used);
		}
		self.drawn_entries = self.transcript.len();
		self.transcript_rows = y;

		// The live band repaints in place at the bottom of the document.
		let animation_frame = Self::animation_frame(elapsed);
		let panel_changed = draw_live_panel(
			&mut self.frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			panel,
			repaint_suffix,
			self.emitted_shards,
			animation_frame,
			self.ctx.charset,
		);
		let working = self.work.borrow().working;
		let working_changed = self.last_working != working;
		if !repaint_suffix && self.last_working && !working {
			self
				.frame
				.fill(Rect::new(0, working_y, viewport.width, 1), base_style());
		}
		if working {
			Self::draw_working(&mut self.frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut self.frame, title_y, self.right_inset);
		if repaint_suffix || editor_changed {
			self
				.frame
				.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);
		}
		let mut damage = SmallVec::new();
		if repaint_suffix {
			damage.push((transcript_damage_start, document_height));
		} else {
			if panel_changed {
				damage.push((panel_y, panel_y.saturating_add(panel_height)));
			}
			if working || working_changed {
				damage.push((working_y, working_y.saturating_add(1)));
			}
			if editor_changed {
				damage.push((editor_y, document_height));
			}
		}
		self.last_working = working;
		self.live_panel = Some(panel);

		RenderedFrame { frame: &self.frame, stable_rows: self.transcript_rows, damage }
	}

	fn generation(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / EMIT_INTERVAL.as_millis()).unwrap_or(u64::MAX)
	}

	fn animation_frame(elapsed: Duration) -> u64 {
		u64::try_from(elapsed.as_millis() / 80).unwrap_or(u64::MAX)
	}

	fn visible_messages(elapsed: Duration) -> usize {
		let interval = MESSAGE_INTERVAL.as_millis();
		usize::try_from(elapsed.as_millis() / interval + 1)
			.unwrap_or(usize::MAX)
			.min(4)
	}

	/// Shards whose permanent result line has been appended by `elapsed`:
	/// two per emit tick, capped well inside `u16` document heights.
	fn finished_shards(elapsed: Duration) -> u16 {
		u16::try_from(Self::generation(elapsed).saturating_mul(2).min(60_000))
			.expect("finished shard count is clamped")
	}

	/// Rows the bottom live band occupies: the shard panel, a blank
	/// separator, the activity row, the title air row, and the editor
	/// block.
	const fn band_height(editor_height: u16) -> u16 {
		LIVE_SHARD_ROWS + 2 + 3 + editor_height
	}

	/// Rows `entry` will occupy at `width`, including its trailing blank.
	fn entry_height(entry: &Entry, width: u16, ctx: &UiContext) -> u16 {
		match entry {
			Entry::Command => 5,
			Entry::Message(message) => {
				let mut scratch = Frame::new(Size::new(width, 48));
				Self::draw_message(&mut scratch, 0, *message, width, ctx.charset)
			},
			Entry::ShardDone(_) => 1,
			Entry::Submitted(submission) => submission.height().saturating_add(1),
		}
	}

	const fn message_width(width: u16) -> u16 {
		let narrowed = width.saturating_sub(3);
		if narrowed == 0 { 1 } else { narrowed }
	}

	/// Paints one transcript entry at `y` and returns the rows it used.
	fn draw_entry_at(&mut self, index: usize, y: u16, width: u16) -> u16 {
		Self::draw_entry(&mut self.frame, &self.transcript[index], y, width, &self.ctx)
	}

	/// Paints `entry` into any frame at `y` and returns the rows it used,
	/// including the trailing blank.
	fn draw_entry(frame: &mut Frame, entry: &Entry, y: u16, width: u16, ctx: &UiContext) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		match entry {
			Entry::Command => {
				draw_command_box(frame, Rect::new(margin, y, content_width, 4), ctx.charset);
				5
			},
			Entry::Message(message) => Self::draw_message(frame, y, *message, width, ctx.charset),
			Entry::ShardDone(shard) => {
				Self::draw_shard_done(frame, y, *shard, width, ctx.charset);
				1
			},
			Entry::Submitted(submission) => {
				draw_submission(frame, y, submission, ctx.charset);
				submission.height().saturating_add(1)
			},
		}
	}

	/// Composes exactly one viewport of throwaway resize-drag content at the
	/// new geometry: the live band anchors to the bottom, then transcript
	/// entries are walked backward and rewrapped at `viewport.width` until
	/// the screen is full — O(viewport) work per drag frame, with the
	/// topmost entry sliced when it only partially fits. Retained transcript
	/// state is untouched, so the settle rebuild replays full history
	/// exactly once.
	pub fn render_resize_preview(&mut self, viewport: Size) -> Frame {
		let elapsed = self.started_at.elapsed();
		let mut frame = Frame::new(viewport);
		if viewport.width == 0 || viewport.height == 0 {
			return frame;
		}
		frame.fill(Rect::new(0, 0, viewport.width, viewport.height), base_style());
		let composer_width = self.composer_width(viewport);
		if self.editor_ui.frame().size().width != composer_width {
			self.editor_ui.resize(composer_width);
		}
		self.editor_ui.tick(elapsed);

		// The live band, laid out exactly like the retained document's.
		let margin = u16::from(viewport.width >= 50);
		let content_width = viewport.width.saturating_sub(margin * 2);
		let editor_height = self.editor_ui.height();
		let editor_y = viewport.height.saturating_sub(editor_height);
		let title_y = editor_y.saturating_sub(1);
		let working_y = title_y.saturating_sub(1);
		let panel_height = LIVE_SHARD_ROWS + 2;
		let panel_y = working_y.saturating_sub(1).saturating_sub(panel_height);
		draw_live_panel(
			&mut frame,
			&mut self.live_rows,
			&mut self.live_label_scratch,
			Rect::new(margin, panel_y, content_width, panel_height),
			true,
			self.emitted_shards,
			Self::animation_frame(elapsed),
			self.ctx.charset,
		);
		if self.work.borrow().working {
			Self::draw_working(&mut frame, working_y, elapsed, self.cancel_hint);
		}
		Self::draw_session_title(&mut frame, title_y, self.right_inset);
		frame.blit(self.editor_ui.frame(), 0, editor_height, 0, editor_y);

		// Transcript tail, bottom-up above the band.
		let mut remaining = panel_y;
		for entry in self.transcript.iter().rev() {
			if remaining == 0 {
				break;
			}
			let height = Self::entry_height(entry, viewport.width, &self.ctx);
			if height == 0 {
				continue;
			}
			if height <= remaining {
				remaining -= height;
				Self::draw_entry(&mut frame, entry, remaining, viewport.width, &self.ctx);
			} else {
				// Slice the bottom rows of the partially visible entry.
				let mut scratch = Frame::new(Size::new(viewport.width, height));
				scratch.fill(Rect::new(0, 0, viewport.width, height), base_style());
				Self::draw_entry(&mut scratch, entry, 0, viewport.width, &self.ctx);
				frame.blit(&scratch, height - remaining, remaining, 0, 0);
				remaining = 0;
			}
		}
		frame
	}

	/// Paints the n-th scripted message and returns rows used including
	/// the trailing blank. Measurement draws into a scratch frame.
	fn draw_message(frame: &mut Frame, y: u16, message: usize, width: u16, charset: Charset) -> u16 {
		let margin = u16::from(width >= 50);
		let content_width = width.saturating_sub(margin * 2);
		if message == 2 {
			draw_edit_box(frame, Rect::new(margin, y, content_width, EDIT_BOX_HEIGHT), charset);
			return EDIT_BOX_HEIGHT + 1;
		}
		let bottom = frame.size().height;
		let spans = Self::message_spans(message);
		// Prose flows edge-to-edge grapheme-exact — no side pads — so every
		// wrapped row re-joins byte-for-byte in native selection.
		let used = draw_flowed(frame, Rect::new(0, y, width, bottom.saturating_sub(y)), &spans);
		used.saturating_add(1)
	}

	fn message_spans(message: usize) -> SmallVec<Span<'static>, 3> {
		let mut spans = SmallVec::new();
		match message {
			0 => {
				spans.push(Span::new("Transcript rows are ", prose_style()));
				spans.push(Span::new("append-only", code_style()));
				spans.push(Span::new(
					": every line is painted once, becomes stable, and rides into native scrollback \
					 with any selection anchored to it.",
					prose_style(),
				));
			},
			1 => {
				spans.push(Span::new(
					"Only the bottom band repaints in place — the live shard panel, the activity \
					 shimmer, and the composer. Rows above it are never rewritten.",
					prose_style(),
				));
			},
			_ => {
				spans.push(Span::new(
					"On terminals that move margin-scrolled rows into scrollback, commits scroll only \
					 the stable transcript through a ",
					prose_style(),
				));
				spans.push(Span::new("DECSTBM top region", code_style()));
				spans.push(Span::new(", so the live band never shifts on screen.", prose_style()));
			},
		}
		spans
	}

	/// Appends a finished shard's permanent one-line result.
	fn draw_shard_done(frame: &mut Frame, y: u16, shard: u16, width: u16, charset: Charset) {
		let margin = u16::from(width >= 50);
		let prefix = fmts!(" {} shard {shard:03} passed", charset.check());
		let detail = fmts!("  workspace-{shard:03}.test.ts  [100%]");
		draw_line(frame, margin + 1, y, width.saturating_sub(margin * 2).saturating_sub(2), &[
			Span::new(prefix.as_str(), ink(GREEN)),
			Span::new(detail.as_str(), ink(MUTED)),
		]);
	}

	/// Shimmering activity line above the editor. The spinner and timer
	/// live in the status bar's brand segment; this row only narrates.
	fn draw_working(frame: &mut Frame, y: u16, elapsed: Duration, hint: &str) {
		if y >= frame.size().height || frame.size().width < 4 {
			return;
		}
		let start = u16::from(frame.size().width >= 50);
		let mut column = start;
		let length = xutf::graphemes_str(WORKING_MESSAGE)
			.count()
			.saturating_add(xutf::graphemes_str(hint).count())
			.saturating_add(1);
		let length = u16::try_from(length).unwrap_or(u16::MAX);
		let shimmer = Shimmer::new(elapsed, SHIMMER_PERIOD, length);
		let right = frame.size().width.saturating_sub(1);
		draw_shimmer(frame, &mut column, start, y, right, hint, shimmer, ink(CYAN));
		draw_shimmer(frame, &mut column, start, y, right, " ", shimmer, ink(GREEN));
		draw_shimmer(frame, &mut column, start, y, right, WORKING_MESSAGE, shimmer, ink(GREEN));
	}

	/// The session title resting right-aligned in the air row between
	/// the working narration and the status band — against the visible
	/// right bound, inside any rail reservation — so the gap reads as
	/// session identity instead of dead space.
	fn draw_session_title(frame: &mut Frame, y: u16, right_inset: u16) {
		let width = frame.size().width.saturating_sub(right_inset);
		let title_width = visible_width(SESSION_TITLE);
		if y >= frame.size().height || width < title_width.saturating_add(2) {
			return;
		}
		let x = width.saturating_sub(title_width.saturating_add(1));
		draw_line(frame, x, y, title_width, &[Span::new(SESSION_TITLE, ink(FAINT).italic())]);
	}
}

/// The closed four-row command box that opens the transcript.
fn draw_command_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 4 || rect.height < 4 {
		return;
	}

	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	let header = [
		Span::new(" PARALLEL TEST RUN ", panel_ink(GREEN).bold()),
		Span::new("results append below · live rows in the bottom panel", panel_ink(MUTED)),
	];
	draw_line(frame, content_x, rect.y + 1, content_width, &header);
	let command = [
		Span::new("$ ", panel_ink(MUTED)),
		Span::new("bun test --parallel=8", panel_ink(CYAN)),
		Span::new(" --timeout=30000 --all-workspaces", panel_ink(TEXT)),
	];
	draw_line(frame, content_x, rect.y + 2, content_width, &command);
}

/// The live band's shard panel: twelve mutable rows that repaint in place
/// every frame and never enter native scrollback.
fn draw_live_panel(
	frame: &mut Frame,
	rows: &mut [LiveRowCache; LIVE_SHARD_ROWS as usize],
	label_scratch: &mut StrMut,
	rect: Rect,
	repaint_chrome: bool,
	emitted_shards: u16,
	animation_frame: u64,
	charset: Charset,
) -> bool {
	let mut changed = repaint_chrome;
	if repaint_chrome {
		draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	}
	if rect.width < 4 || rect.height < 3 {
		return changed;
	}

	if repaint_chrome {
		let title = [
			Span::new(" LIVE SHARDS ", panel_ink(GREEN).bold()),
			Span::new("mutable rows repaint in place ", panel_ink(MUTED)),
		];
		draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	}
	let content_x = rect.x + 2;
	let content_width = rect.width.saturating_sub(4);
	for row in 0..rect.height.saturating_sub(2) {
		let shard = emitted_shards.saturating_add(row).saturating_add(1);
		let phase = (u64::from(row) + animation_frame) % 11;
		let (prefix_phase, symbol, state, state_style, progress) = match phase {
			0 => (
				0,
				"⠼",
				"running",
				panel_ink(GREEN).bold(),
				(u64::from(row) * 17 + animation_frame * 7) % 100,
			),
			1..=7 => {
				(1, "·", "working", panel_ink(MUTED), (u64::from(row) * 17 + animation_frame * 7) % 100)
			},
			_ => (2, "·", "queued ", panel_ink(FAINT), 0),
		};
		let row_y = rect.y + 1 + row;
		let right = content_x
			.saturating_add(content_width)
			.min(frame.size().width);
		let cache = &mut rows[usize::from(row)];
		let prefix_changed = repaint_chrome
			|| !cache.prefix_valid
			|| cache.prefix_shard != shard
			|| cache.prefix_phase != prefix_phase;
		changed |= prefix_changed;
		let label_x = if prefix_changed {
			let prefix = fmts!(" {symbol} shard {shard:03} ");
			let prefix_width = prefix.len().saturating_sub(symbol.len()).saturating_add(1);
			let next_x = content_x
				.saturating_add(u16::try_from(prefix_width).unwrap_or(u16::MAX))
				.saturating_add(u16::try_from(state.len()).unwrap_or(u16::MAX))
				.saturating_add(2)
				.min(right);
			if !repaint_chrome && cache.label_x != next_x {
				clear_cached_label(frame, cache, row_y, right);
			}
			let next_x = draw_line(frame, content_x, row_y, content_width, &[
				Span::new(prefix.as_str(), state_style),
				Span::new(state, state_style),
				Span::new("  ", panel_ink(FAINT)),
			]);
			cache.prefix_shard = shard;
			cache.prefix_phase = prefix_phase;
			cache.prefix_valid = true;
			next_x
		} else {
			cache.label_x
		};
		let moved = cache.label_x != label_x;
		let label_changed = repaint_chrome
			|| moved
			|| !cache.label_valid
			|| cache.label_shard != shard
			|| cache.label_progress != progress;
		changed |= label_changed;
		if label_changed {
			label_scratch.truncate(0);
			write!(label_scratch, "workspace-{shard:03}.test.ts  [{progress:>3}%]")
				.expect("shard label formatting is infallible");
			let resized = cache.label.len() != label_scratch.len();
			if !repaint_chrome && resized && !moved {
				clear_cached_label(frame, cache, row_y, right);
			}
			let width = right.saturating_sub(label_x);
			if repaint_chrome || moved || resized {
				frame.put_clipped(label_x, row_y, width, label_scratch.as_str(), panel_ink(MUTED));
			} else {
				draw_ascii_changes(
					frame,
					label_x,
					row_y,
					width,
					cache.label.as_str(),
					label_scratch.as_str(),
					panel_ink(MUTED),
				);
			}
			std::mem::swap(&mut cache.label, label_scratch);
			cache.label_shard = shard;
			cache.label_progress = progress;
			cache.label_valid = true;
		}
		cache.label_x = label_x;
	}
	changed
}

fn clear_cached_label(frame: &mut Frame, cache: &LiveRowCache, y: u16, right: u16) {
	if cache.label.is_empty() {
		return;
	}
	let width = u16::try_from(cache.label.len())
		.unwrap_or(u16::MAX)
		.min(right.saturating_sub(cache.label_x));
	frame.fill(Rect::new(cache.label_x, y, width, 1), panel_style());
}

/// Repaints only changed byte runs within an equal-length ASCII label.
fn draw_ascii_changes(
	frame: &mut Frame,
	x: u16,
	y: u16,
	width: u16,
	previous: &str,
	next: &str,
	style: Style,
) {
	if width == 0 || previous == next {
		return;
	}
	if previous.len() != next.len() || !previous.is_ascii() || !next.is_ascii() {
		frame.put_clipped(x, y, width, next, style);
		return;
	}
	let previous = previous.as_bytes();
	let next_bytes = next.as_bytes();
	let limit = previous.len().min(usize::from(width));
	let mut index = 0;
	while index < limit {
		while index < limit && previous[index] == next_bytes[index] {
			index += 1;
		}
		let start = index;
		while index < limit && previous[index] != next_bytes[index] {
			index += 1;
		}
		if start < index {
			let offset = u16::try_from(start).unwrap_or(u16::MAX);
			frame.put_clipped(
				x.saturating_add(offset),
				y,
				u16::try_from(index - start).unwrap_or(u16::MAX),
				&next[start..index],
				style,
			);
		}
	}
}

fn draw_edit_box(frame: &mut Frame, rect: Rect, charset: Charset) {
	draw_box(frame, rect, ink(FAINT), panel_style(), charset);
	if rect.width < 8 || rect.height < EDIT_BOX_HEIGHT {
		return;
	}

	let title = [
		Span::new(" Live ", panel_ink(GREEN).bold()),
		Span::new("band · selection semantics ", panel_ink(CYAN)),
	];
	draw_line(frame, rect.x + 2, rect.y, rect.width.saturating_sub(4), &title);
	draw_line(frame, rect.x + 2, rect.y + 1, rect.width.saturating_sub(4), &[
		Span::new(charset.check(), panel_ink(GREEN).bold()),
		Span::new(" ", panel_ink(GREEN)),
		Span::new("Transcript selections ride with the text", panel_ink(TEXT)),
	]);
	draw_line(frame, rect.x + 2, rect.y + 2, rect.width.saturating_sub(4), &[Span::new(
		"  margin commits pin the band on kitty-class terminals",
		panel_ink(MUTED),
	)]);
}

/// Paints a submitted message: the prompt gutter, then the rendered
/// Markdown document blitted beside it (or the raw lines when the text
/// isn't renderable as Markdown).
fn draw_submission(frame: &mut Frame, y: u16, submission: &Submission, charset: Charset) {
	if frame.size().width < 4 {
		return;
	}
	let Some(view) = &submission.view else {
		for (offset, line) in submission.text.split('\n').enumerate() {
			let Ok(offset) = u16::try_from(offset) else {
				break;
			};
			let row = y.saturating_add(offset);
			if row >= frame.size().height {
				break;
			}
			let prompt = if offset == 0 { charset.cursor() } else { "  " };
			let text_x = frame.put(1, row, prompt, ink(GREEN).bold());
			let width = frame
				.size()
				.width
				.saturating_sub(1)
				.saturating_sub(text_x.saturating_sub(1));
			draw_submission_text(frame, text_x, row, width, line, charset);
		}
		return;
	};
	frame.put(1, y, charset.cursor(), ink(GREEN).bold());
	frame.blit(view.frame(), 0, view.height(), 3, y);
}

Trait Implementations

impl Clone for Frame

fn clone(&self) -> Frame

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Frame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.