Struct Ui 

pub struct Ui { /* private fields */ }

A parsed, laid-out, retained component tree painting into a Frame.

Implementations

impl Ui

pub fn from_markup( source: impl Into<Str>, width: u16, ctx: UiContext, ) -> Result<Self, ParseError>

Parses runtime markup and produces the first fully painted frame.

Prefer Ui::from_root with crate::dom! when the structure is known at compile time; this path is for markup that only exists at runtime (configuration, generated text, editable source).

Errors

Returns ParseError for malformed markup.

Examples found in repository

examples/chat/demo.rs (line 237)

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

examples/tml.rs (line 18)

fn build(source: &str, width: u16, ctx: &UiContext) -> Ui {
	match Ui::from_markup(source, width, ctx.clone()) {
		Ok(ui) => ui,
		Err(error) => {
			let message = error.to_string();
			Ui::from_root(
				dom! {
					<box border=round bc=err title="parse error" pad="0 1">
						<text fg=err>{message}</text>
					</box>
				},
				width,
				ctx.clone(),
			)
		},
	}
}

pub fn from_root(root: impl IntoComponent, width: u16, ctx: UiContext) -> Self

Builds a retained UI directly from a component tree.

Examples found in repository

examples/chat/picker.rs (line 538)

fn build(
	mode: Mode,
	tier: PerfTier,
	current: usize,
	query: &str,
	rows: u16,
	width: u16,
	ctx: &UiContext,
) -> Ui {
	Ui::from_root(tree(mode, tier, current, query, rows, ctx.charset), width, ctx.clone())
}

examples/tml.rs (lines 22-30)

fn build(source: &str, width: u16, ctx: &UiContext) -> Ui {
	match Ui::from_markup(source, width, ctx.clone()) {
		Ok(ui) => ui,
		Err(error) => {
			let message = error.to_string();
			Ui::from_root(
				dom! {
					<box border=round bc=err title="parse error" pad="0 1">
						<text fg=err>{message}</text>
					</box>
				},
				width,
				ctx.clone(),
			)
		},
	}
}

examples/chat/commands.rs (lines 212-233)

fn build(query: &str, rows: u16, width: u16, ctx: &UiContext) -> Ui {
	let list = entries();
	let seed = Str::from(query);
	let height = rows.saturating_add(1);
	Ui::from_root(
		dom! {
			<box border=round title="Commands" pad-x=1>
				<col>
					<select id="commands" filter={seed} h={height}>
						for entry in list {
							<option value={entry.value} label={entry.label}>
								<td><pre fg={entry.name_fg}>{entry.name}</pre></td>
								<td truncate grow><pre fg={DIM}>{entry.detail}</pre></td>
								if !entry.key.is_empty() {
									<td align=end><pre fg={DIM}>{entry.key}</pre></td>
								}
							</option>
						}
					</select>
					<text dim truncate>{HINT}</text>
				</col>
			</box>
		},
		width,
		ctx.clone(),
	)
}

examples/chat/sidebar.rs (lines 172-209)

fn build(model: &str, ctx: &UiContext) -> Ui {
	let files = FILES;
	Ui::from_root(
		dom! {
			<row id="rail" h=24>
				<hr/>
				<col id="body" h=24 grow pad="0 1" gap=1>
					<text bold fg={CYAN}>{"session"}</text>
					<col>
						<row gap=1>
							<text fg={DIM} w=8>{"model"}</text>
							<text id="model" truncate>{model}</text>
						</row>
						<row gap=1>
							<text fg={DIM} w=8>{"elapsed"}</text>
							<text id="elapsed">{"0:00"}</text>
						</row>
						<row gap=1>
							<text fg={DIM} w=8>{"branch"}</text>
							<text truncate>{"tui/seam-commits"}</text>
						</row>
					</col>
					<hr/>
					<text bold fg={CYAN}>{"files"}</text>
					<select id="files" h={files.len() as u16}>
						for (name, delta) in files {
							<option value={name} label={name}>
								<td grow truncate><pre>{name}</pre></td>
								<td align=end><pre fg={GREEN}>{delta}</pre></td>
							</option>
						}
					</select>
					<spacer grow/>
					<text dim truncate>{"ctrl+b rail · esc back"}</text>
				</col>
			</row>
		},
		WIDTH,
		ctx.clone(),
	)
}

examples/chat/demo.rs (line 769)

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

examples/companies.rs (line 153)

fn build_ui(viewport: Size, context: UiContext) -> Ui {
	let ids = PROVIDERS
		.iter()
		.enumerate()
		.map(|(index, provider)| {
			(format!("{ASSET_DIR}/{}.png", provider.id), u32::try_from(index + 1).unwrap())
		})
		.collect::<HashMap<_, _>>();
	let elements = Elements::builder()
		.with("logo", move |_: &str, props: Props, _: Vec<Cached>| {
			let source = props.str_of(Prop::Src).map_or("", |value| value.as_str());
			let id = ids.get(source).copied().unwrap_or(1);
			Box::new(
				Img::new()
					.with_str(Prop::Src, source)
					.with(Prop::W, 4_u16)
					.kitty(id, 2, 4),
			) as Box<dyn omp_tui::Component>
		})
		.build();
	let root = dom! {
		<col gap=1>
			<row gap=1>
				<i:log-in/>
				<text bold fg="accent..info">{"Choose a provider"}</text>
				<text dim>{format!("{} providers", PROVIDERS.len())}</text>
			</row>
			<scroll id={SCROLL_ID} h={scroll_height(viewport)}>
				<row wrap gap=1 justify=center>
					for provider in PROVIDERS.iter() {
						<box focus id={provider.id} w={CARD_W} border=round bc="muted..muted"
							hover="#38bdf8..#c084fc" lift=1 anim=220 ease=in-out
							align=center pad-x=1>
							<logo src={format!("{ASSET_DIR}/{}.png", provider.id)}/>
							<text bold truncate align=center>{provider.name}</text>
						</box>
					}
				</row>
			</scroll>
			<row gap=2>
				<text dim>{"↹/←→/↑↓ pick · ↵ login · wheel scroll · Ctrl-C quit"}</text>
				<text id={HUD_ID} dim>{"repaint: 0 cells"}</text>
			</row>
		</col>
	};
	let context = UiContext { elements, ..context };
	Ui::from_root(root, viewport.width, context)
}

Additional examples can be found in:

• examples/gallery/main.rs

pub const fn frame(&self) -> &Frame

The retained document frame.

Examples found in repository

examples/chat/demo.rs (line 979)

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

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/chat/sidebar.rs (line 155)

	pub fn layer(&mut self, viewport: Size, elapsed: Duration) -> Option<Layer<'_>> {
		if !self.visible(viewport) {
			if self.focused {
				self.blur();
			}
			return None;
		}
		if self.height != viewport.height {
			self.height = viewport.height;
			self.ui.set_prop("rail", Prop::H, viewport.height);
			self.ui.set_prop("body", Prop::H, viewport.height);
		}
		let seconds = elapsed.as_secs();
		if seconds != self.elapsed_seconds {
			self.elapsed_seconds = seconds;
			self.ui.set_text("elapsed", elapsed_label(seconds));
		}
		Some(Layer { frame: self.ui.frame(), options: &self.options, active: self.focused })
	}

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

pub const fn context(&self) -> &UiContext

The presentation context this tree renders with.

pub fn set_context(&mut self, ctx: UiContext) -> bool

Swaps the presentation context and refreshes the whole document.

Applies ctx to this tree and every stacked overlay, advances the cache revision so geometry and render memos discard context-derived output, then relays out and repaints. A context that compares equal (appearance, charset, graphics, Jamo policy, theme, elements) is a no-op returning false. The presentation clock is retained, and a context without an image loader keeps the installed one. Structure parsed from markup is retained: swapping elements affects future parses only.

pub const fn height(&self) -> u16

Document height in rows after the last layout.

Examples found in repository

examples/chat/demo.rs (line 865)

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

pub fn has_damage(&self) -> bool

Whether a present is needed after the most recent mutation.

pub fn take_frame_damage(&mut self) -> bool

Consumes raw-frame damage after an embedder copies Ui::frame.

Examples found in repository

examples/chat/demo.rs (line 1023)

	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_text(&mut self, id: &str, text: impl Into<Str>) -> bool

Replaces a named component’s text and refreshes the smallest safe region.

Examples found in repository

examples/chat/sidebar.rs (line 131)

	pub fn set_model(&mut self, name: &str) {
		self.ui.set_text("model", name);
	}

	/// The composited rail for this frame, laid out to the full viewport
	/// height; `None` when toggled off or gated out by a small viewport.
	/// Shrinking below the minimum blurs the rail so keys never route into
	/// an invisible layer.
	pub fn layer(&mut self, viewport: Size, elapsed: Duration) -> Option<Layer<'_>> {
		if !self.visible(viewport) {
			if self.focused {
				self.blur();
			}
			return None;
		}
		if self.height != viewport.height {
			self.height = viewport.height;
			self.ui.set_prop("rail", Prop::H, viewport.height);
			self.ui.set_prop("body", Prop::H, viewport.height);
		}
		let seconds = elapsed.as_secs();
		if seconds != self.elapsed_seconds {
			self.elapsed_seconds = seconds;
			self.ui.set_text("elapsed", elapsed_label(seconds));
		}
		Some(Layer { frame: self.ui.frame(), options: &self.options, active: self.focused })
	}

examples/gallery/render.rs (line 129)

pub(crate) fn sync_preview(ui: &mut Ui, synced: &mut String) {
	let text = ui.values()["src"].as_str().unwrap_or_default().to_owned();
	if text != *synced {
		ui.set_text("preview", text.clone());
		*synced = text;
	}
}

examples/gallery/anim.rs (line 115)

	fn mood(&mut self, ui: &mut Ui) {
		self.mood = (self.mood + 1) % MOODS.len();
		let (token, bg, text) = MOODS[self.mood];
		ui.set_prop("mood", Prop::Bc, token);
		ui.set_prop("mood", Prop::Bg, bg);
		ui.set_prop("mood-text", Prop::Fg, token);
		ui.set_text("mood-text", text);
	}

examples/companies.rs (lines 164-173)

fn show_stats(app: &mut App, chosen: Option<&str>) {
	let caps = app.caps();
	let stats = app.last_stats();
	let pixels = caps.cell_px.map_or_else(
		|| "cell-px ?".to_owned(),
		|(width, height)| format!("cell-px {width}×{height}"),
	);
	let login = chosen.map_or(String::new(), |id| format!("login: {id} · "));
	app.ui_mut().set_text(
		HUD_ID,
		format!(
			"{login}{} · {} · {} · repaint: {} cells",
			graphics_label(caps.graphics),
			caps.id,
			pixels,
			stats.changed_cells,
		),
	);
}

examples/chat/picker.rs (line 381)

pub fn show_detail_on(ui: &mut Ui, model: Option<usize>) {
	let facts = model.map_or_else(|| Str::new_static(" "), |index| facts(&MODELS[index]));
	ui.set_text("facts", facts);
	// Hide before show: the document must never transiently exceed its
	// steady height — a raw-frame layer's retained frame keeps the
	// high-water mark, which would leave a stale extra row.
	for index in (0..MODELS.len()).filter(|&index| model != Some(index)) {
		ui.set_visible(&fmts!("chips-{index}"), false);
	}
	if let Some(index) = model {
		ui.set_visible(&fmts!("chips-{index}"), true);
	}
}

examples/gallery/main.rs (line 170)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.quit([Key::Ctrl('c'), Key::Ctrl('q')])
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	// The picker tab opens with the first model's details, like the chat
	// overlay does.
	picker::show_detail_on(app.ui_mut(), Some(0));

	let mut synced = String::new();
	let mut lab = anim::Lab::new();
	let mut layers = Layers::default();
	let mut next_step = tokio::time::Instant::now() + anim::AUTOPLAY_STEP;

	loop {
		let event = tokio::select! {
			event = app.next() => match event? {
				Some(event) => event,
				None => break,
			},
			() = tokio::time::sleep_until(next_step) => {
				if lab.autoplay && active_tab(app.ui()) == "Anim" {
					lab.advance(app.ui_mut());
				}
				next_step += anim::AUTOPLAY_STEP;
				continue;
			},
		};
		match event {
			AppEvent::Resized(viewport) => {
				for pane in render::PANE_IDS {
					app.ui_mut().set_height(pane, render::pane_height(viewport));
				}
			},
			AppEvent::Key(key) => match active_tab(app.ui()).as_str() {
				"Anim" => lab.handle_key(key, app.ui_mut()),
				"Overlay" => match key {
					Key::Ctrl('k') if layers.picker.is_none() => {
						layers.picker = Some(overlay::show_picker(app.ui_mut()));
					},
					Key::Ctrl('g') => match layers.help.take() {
						Some(id) => {
							app.ui_mut().close_overlay(id);
						},
						None => layers.help = Some(overlay::show_help(app.ui_mut())),
					},
					_ => {},
				},
				_ => {},
			},
			// The Overlay tab's modal select committed a model.
			AppEvent::Changed { id, value } if id == "model" => {
				if let Some(overlay) = layers.picker.take() {
					let label = overlay::MODELS
						.iter()
						.find(|(short, ..)| *short == value)
						.map_or(value.as_str(), |(_, label, _)| label);
					app.ui_mut().set_text("status", format!("model: {label}"));
					app.ui_mut().close_overlay(overlay);
				}
			},
			// The Picker tab's select moved: mirror the chat picker's
			// facts-and-chips detail line.
			AppEvent::Highlighted { id, value } if id == "models" => {
				picker::show_detail_on(app.ui_mut(), value.as_str().parse().ok());
			},
			AppEvent::Filtered { id, value, .. } if id == "models" => {
				let model = value.and_then(|value| value.as_str().parse().ok());
				picker::show_detail_on(app.ui_mut(), model);
			},
			AppEvent::OverlayClosed(id) => {
				if layers.picker == Some(id) {
					layers.picker = None;
				}
				if layers.help == Some(id) {
					layers.help = None;
				}
			},
			_ => {},
		}
		render::sync_preview(app.ui_mut(), &mut synced);
		// Reserve the Overlay tab's chords only while it is showing, so the
		// focused composer can't spend Ctrl+K on kill-line — and the Live
		// tab's editor keeps it.
		let chords: &[Key] = if active_tab(app.ui()) == "Overlay" {
			&[Key::Ctrl('k'), Key::Ctrl('g')]
		} else {
			&[]
		};
		app.set_hotkeys(chords.iter().copied());
	}
	Ok(())
}

pub fn set_prop( &mut self, id: &str, prop: Prop, value: impl Into<PropValue>, ) -> bool

Sets a named component’s property and refreshes the smallest safe region. Size properties relayout the document; components with an anim property tween toward the new value from whatever is on screen. A matching value is a no-op. Returns false for an unknown id.

Panics

Panics when a textual value is invalid for prop, matching [Props::set].

Examples found in repository

examples/gallery/anim.rs (line 105)

	fn race(&mut self, ui: &mut Ui) {
		self.race_wide = !self.race_wide;
		let target = if self.race_wide { "88%" } else { "12%" };
		for (id, _) in BARS {
			ui.set_prop(id, Prop::W, target);
		}
	}

	fn mood(&mut self, ui: &mut Ui) {
		self.mood = (self.mood + 1) % MOODS.len();
		let (token, bg, text) = MOODS[self.mood];
		ui.set_prop("mood", Prop::Bc, token);
		ui.set_prop("mood", Prop::Bg, bg);
		ui.set_prop("mood-text", Prop::Fg, token);
		ui.set_text("mood-text", text);
	}

	fn palette(&mut self, ui: &mut Ui) {
		self.palette = (self.palette + 1) % PALETTES.len();
		ui.set_prop("hero", Prop::Bg, PALETTES[self.palette]);
	}

	fn sidebar(&mut self, ui: &mut Ui) {
		self.sidebar_wide = !self.sidebar_wide;
		ui.set_prop("sidebar", Prop::W, if self.sidebar_wide { 30_u16 } else { 14 });
	}

examples/chat/picker.rs (line 317)

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

examples/chat/commands.rs (line 116)

	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/chat/sidebar.rs (line 147)

	pub fn layer(&mut self, viewport: Size, elapsed: Duration) -> Option<Layer<'_>> {
		if !self.visible(viewport) {
			if self.focused {
				self.blur();
			}
			return None;
		}
		if self.height != viewport.height {
			self.height = viewport.height;
			self.ui.set_prop("rail", Prop::H, viewport.height);
			self.ui.set_prop("body", Prop::H, viewport.height);
		}
		let seconds = elapsed.as_secs();
		if seconds != self.elapsed_seconds {
			self.elapsed_seconds = seconds;
			self.ui.set_text("elapsed", elapsed_label(seconds));
		}
		Some(Layer { frame: self.ui.frame(), options: &self.options, active: self.focused })
	}

pub fn set_visible(&mut self, id: &str, visible: bool) -> bool

Shows or hides a named component and relayouts the document; a hidden component skips layout, paint, focus, and hit-testing. Prefer when= conditions for value-driven visibility — this is the imperative counterpart for hosts driving visibility from app state (a detail pane following a list cursor). Returns false for an unknown id.

Examples found in repository

examples/chat/picker.rs (line 386)

pub fn show_detail_on(ui: &mut Ui, model: Option<usize>) {
	let facts = model.map_or_else(|| Str::new_static(" "), |index| facts(&MODELS[index]));
	ui.set_text("facts", facts);
	// Hide before show: the document must never transiently exceed its
	// steady height — a raw-frame layer's retained frame keeps the
	// high-water mark, which would leave a stale extra row.
	for index in (0..MODELS.len()).filter(|&index| model != Some(index)) {
		ui.set_visible(&fmts!("chips-{index}"), false);
	}
	if let Some(index) = model {
		ui.set_visible(&fmts!("chips-{index}"), true);
	}
}

pub fn tick(&mut self, now: Duration) -> bool

Advances the deterministic presentation clock and repaints every component whose wake deadline has passed.

crate::App drives this clock in production; tests and custom hosts can supply their own monotonic Duration. Returns whether anything repainted.

Examples found in repository

examples/chat/demo.rs (line 1022)

	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
	}

pub fn next_wake(&self) -> Option<Duration>

Earliest pending animation deadline, if any component is animating. crate::App schedules it; custom hosts may do the same.

pub fn invalidate(&mut self, id: &str) -> bool

Refreshes a named component whose externally shared state changed.

The out-of-band companion to event routing: components that read application state through interior mutability cannot be reached by a key or mouse path, so the owner mutates the state and invalidates the component by id. Returns false for an unknown id.

Examples found in repository

examples/chat/demo.rs (line 892)

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

examples/companies.rs (line 207)

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

pub fn resize(&mut self, width: u16)

Relayouts and repaints everything at a new width.

Examples found in repository

examples/chat/demo.rs (line 981)

	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/chat/picker.rs (line 320)

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

pub fn set_height(&mut self, id: &str, height: u16) -> bool

Sets a named component’s fixed height.

Examples found in repository

examples/gallery/anim.rs (line 130)

	fn drawer(&mut self, ui: &mut Ui) {
		self.drawer_open = !self.drawer_open;
		ui.set_height("drawer", if self.drawer_open { 10 } else { 4 });
	}

examples/companies.rs (line 214)

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

examples/gallery/main.rs (line 144)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.quit([Key::Ctrl('c'), Key::Ctrl('q')])
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	// The picker tab opens with the first model's details, like the chat
	// overlay does.
	picker::show_detail_on(app.ui_mut(), Some(0));

	let mut synced = String::new();
	let mut lab = anim::Lab::new();
	let mut layers = Layers::default();
	let mut next_step = tokio::time::Instant::now() + anim::AUTOPLAY_STEP;

	loop {
		let event = tokio::select! {
			event = app.next() => match event? {
				Some(event) => event,
				None => break,
			},
			() = tokio::time::sleep_until(next_step) => {
				if lab.autoplay && active_tab(app.ui()) == "Anim" {
					lab.advance(app.ui_mut());
				}
				next_step += anim::AUTOPLAY_STEP;
				continue;
			},
		};
		match event {
			AppEvent::Resized(viewport) => {
				for pane in render::PANE_IDS {
					app.ui_mut().set_height(pane, render::pane_height(viewport));
				}
			},
			AppEvent::Key(key) => match active_tab(app.ui()).as_str() {
				"Anim" => lab.handle_key(key, app.ui_mut()),
				"Overlay" => match key {
					Key::Ctrl('k') if layers.picker.is_none() => {
						layers.picker = Some(overlay::show_picker(app.ui_mut()));
					},
					Key::Ctrl('g') => match layers.help.take() {
						Some(id) => {
							app.ui_mut().close_overlay(id);
						},
						None => layers.help = Some(overlay::show_help(app.ui_mut())),
					},
					_ => {},
				},
				_ => {},
			},
			// The Overlay tab's modal select committed a model.
			AppEvent::Changed { id, value } if id == "model" => {
				if let Some(overlay) = layers.picker.take() {
					let label = overlay::MODELS
						.iter()
						.find(|(short, ..)| *short == value)
						.map_or(value.as_str(), |(_, label, _)| label);
					app.ui_mut().set_text("status", format!("model: {label}"));
					app.ui_mut().close_overlay(overlay);
				}
			},
			// The Picker tab's select moved: mirror the chat picker's
			// facts-and-chips detail line.
			AppEvent::Highlighted { id, value } if id == "models" => {
				picker::show_detail_on(app.ui_mut(), value.as_str().parse().ok());
			},
			AppEvent::Filtered { id, value, .. } if id == "models" => {
				let model = value.and_then(|value| value.as_str().parse().ok());
				picker::show_detail_on(app.ui_mut(), model);
			},
			AppEvent::OverlayClosed(id) => {
				if layers.picker == Some(id) {
					layers.picker = None;
				}
				if layers.help == Some(id) {
					layers.help = None;
				}
			},
			_ => {},
		}
		render::sync_preview(app.ui_mut(), &mut synced);
		// Reserve the Overlay tab's chords only while it is showing, so the
		// focused composer can't spend Ctrl+K on kill-line — and the Live
		// tab's editor keeps it.
		let chords: &[Key] = if active_tab(app.ui()) == "Overlay" {
			&[Key::Ctrl('k'), Key::Ctrl('g')]
		} else {
			&[]
		};
		app.set_hotkeys(chords.iter().copied());
	}
	Ok(())
}

pub fn present<W: Write>( &mut self, renderer: &mut Renderer<W>, viewport_height: u16, stable_rows: u16, ) -> Result<PaintStats>

Presents the retained frame without copying it, compositing every visible overlay above the document for this viewport.

Errors

Propagates the renderer’s contract and writer errors.

pub fn preview<W: Write>( &mut self, renderer: &mut Renderer<W>, viewport_height: u16, leading_sequence: &str, ) -> Result<PaintStats>

Paints the composited viewport as a throwaway frame, leaving the renderer’s committed history untouched.

Alternate-screen presentation: hosts holding the alternate screen — for a modal overlay or a fullscreen scene — repaint with this on every damage or geometry change, and leading_sequence lets the buffer switch ride the same synchronized update (see Terminal::stage_alt_enter). Damage is consumed exactly like Ui::present.

Errors

Propagates the renderer’s contract and writer errors.

pub fn compose_resize_tail(&mut self, viewport: Size) -> Option<Frame>

Composes one screen of throwaway drag content at viewport without relayouting the retained tree.

The root’s tail children (crate::Component::resize_tail) are composed bottom-up at the new width until the viewport is full — O(viewport) work per drag frame. Nested vertical stacks (including the implicit markup root) are walked recursively without ever computing their full height, and a leaf taller than the space left is sliced to its bottom rows, so work stays bounded by the screen rather than document history. None means the root has no tail fast path; callers fall back to a full Ui::resize. Child placement is transient: the deferred Ui::resize at settle re-places everything.

pub fn handle_key(&mut self, key: Key) -> UiEvent

Routes a key to the layer holding the keyboard — the topmost visible modal overlay, else the non-modal layer focused through Ui::focus_overlay or a click — falling back to the base tree’s focused component with focus-ring fallback.

Examples found in repository

examples/chat/sidebar.rs (line 99)

	pub fn handle_key(&mut self, key: Key) {
		if self.ui.handle_key(key) == UiEvent::Cancel {
			self.blur();
		}
	}

examples/chat/picker.rs (line 281)

	pub fn handle_key(&mut self, key: Key) -> PickerEvent {
		let event = self.ui.handle_key(key);
		self.route(event)
	}

examples/chat/commands.rs (line 83)

	pub fn handle_key(&mut self, key: Key) -> PaletteEvent {
		let event = self.ui.handle_key(key);
		self.route(event)
	}

examples/chat/demo.rs (line 803)

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

pub fn handle_paste(&mut self, text: &str) -> UiEvent

Routes sanitized paste text to the focused component; the returned event mirrors Ui::handle_key.

Examples found in repository

examples/chat/picker.rs (line 287)

	pub fn handle_paste(&mut self, text: &str) -> PickerEvent {
		let event = self.ui.handle_paste(text);
		self.route(event)
	}

examples/chat/commands.rs (line 89)

	pub fn handle_paste(&mut self, text: &str) -> PaletteEvent {
		let event = self.ui.handle_paste(text);
		self.route(event)
	}

examples/chat/demo.rs (line 920)

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

pub fn handle_paste_raw(&mut self, text: &str) -> UiEvent

Routes paste text for verbatim insertion ([Component::paste_raw]): no drop classification, no large-paste collapse. Backs the Ctrl+Shift+V clipboard fallback.

Examples found in repository

examples/chat/demo.rs (line 927)

	pub fn handle_paste_raw(&mut self, text: &str) {
		let _ = self.editor_ui.handle_paste_raw(text);
	}

pub fn focus_first(&mut self)

Moves focus to the first focusable component when nothing is focused yet, activating keyboard chrome.

The entry half of a raw-frame layer host’s keyboard hand-off; Ui::blur is the exit half. Retained stacks get both through Ui::focus_overlay and Ui::blur_overlay.

Examples found in repository

examples/chat/sidebar.rs (line 91)

	pub fn toggle(&mut self) {
		self.open = !self.open;
		if self.open {
			self.focused = true;
			self.ui.focus_first();
		} else {
			self.blur();
		}
	}

	/// Routes a key while the rail holds the keyboard; `Esc` hands it back.
	pub fn handle_key(&mut self, key: Key) {
		if self.ui.handle_key(key) == UiEvent::Cancel {
			self.blur();
		}
	}

	/// Routes a mouse report through the rail's band. A click inside takes
	/// the keyboard, a click outside returns it; `false` means the gesture
	/// was not consumed and belongs to the transcript.
	pub fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> bool {
		if !self.open {
			return false;
		}
		if self
			.ui
			.handle_mouse_as_layer(&self.options, viewport, col, row, kind)
			.is_some()
		{
			if kind == Mouse::Click && !self.focused {
				self.focused = true;
				self.ui.focus_first();
			}
			true
		} else {
			if kind == Mouse::Click {
				self.blur();
			}
			false
		}
	}

pub fn blur(&mut self)

Clears this tree’s focus, removing focus chrome and the caret.

Raw-frame layer hosts call this when the keyboard returns to the document, so no stale chrome suggests typing still lands here.

Examples found in repository

examples/chat/sidebar.rs (line 65)

	pub fn new(model: &str, ctx: &UiContext) -> Self {
		let options = OverlayOptions::default()
			.anchor(OverlayAnchor::Right)
			.width(Dim::Cells(WIDTH))
			.non_modal()
			.min_viewport(MIN_VIEWPORT);
		let mut ui = build(model, ctx);
		// The rail starts without the keyboard: no focus chrome or frame
		// cursor until `toggle` or a click hands it over.
		ui.blur();
		Self { ui, options, open: true, focused: false, elapsed_seconds: 0, height: 0 }
	}

	/// Whether the rail composites for `viewport`.
	const fn visible(&self, viewport: Size) -> bool {
		self.open && viewport.width >= MIN_VIEWPORT.width && viewport.height >= MIN_VIEWPORT.height
	}

	/// Columns the rail reserves at `viewport`: its full width while
	/// composited, zero when toggled off or gated out. The composer docks
	/// its right-aligned chrome against the remaining width.
	pub const fn reserved(&self, viewport: Size) -> u16 {
		if self.visible(viewport) { WIDTH } else { 0 }
	}

	/// Whether the rail currently holds the keyboard.
	pub const fn focused(&self) -> bool {
		self.focused
	}

	/// `Ctrl+B`: opening hands the rail the keyboard, closing returns it.
	pub fn toggle(&mut self) {
		self.open = !self.open;
		if self.open {
			self.focused = true;
			self.ui.focus_first();
		} else {
			self.blur();
		}
	}

	/// Routes a key while the rail holds the keyboard; `Esc` hands it back.
	pub fn handle_key(&mut self, key: Key) {
		if self.ui.handle_key(key) == UiEvent::Cancel {
			self.blur();
		}
	}

	/// Routes a mouse report through the rail's band. A click inside takes
	/// the keyboard, a click outside returns it; `false` means the gesture
	/// was not consumed and belongs to the transcript.
	pub fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> bool {
		if !self.open {
			return false;
		}
		if self
			.ui
			.handle_mouse_as_layer(&self.options, viewport, col, row, kind)
			.is_some()
		{
			if kind == Mouse::Click && !self.focused {
				self.focused = true;
				self.ui.focus_first();
			}
			true
		} else {
			if kind == Mouse::Click {
				self.blur();
			}
			false
		}
	}

	/// Reflects a session model switch in the rail's model row.
	pub fn set_model(&mut self, name: &str) {
		self.ui.set_text("model", name);
	}

	/// The composited rail for this frame, laid out to the full viewport
	/// height; `None` when toggled off or gated out by a small viewport.
	/// Shrinking below the minimum blurs the rail so keys never route into
	/// an invisible layer.
	pub fn layer(&mut self, viewport: Size, elapsed: Duration) -> Option<Layer<'_>> {
		if !self.visible(viewport) {
			if self.focused {
				self.blur();
			}
			return None;
		}
		if self.height != viewport.height {
			self.height = viewport.height;
			self.ui.set_prop("rail", Prop::H, viewport.height);
			self.ui.set_prop("body", Prop::H, viewport.height);
		}
		let seconds = elapsed.as_secs();
		if seconds != self.elapsed_seconds {
			self.elapsed_seconds = seconds;
			self.ui.set_text("elapsed", elapsed_label(seconds));
		}
		Some(Layer { frame: self.ui.frame(), options: &self.options, active: self.focused })
	}

	fn blur(&mut self) {
		self.focused = false;
		self.ui.blur();
	}

pub fn handle_mouse(&mut self, x: u16, y: u16, mouse: Mouse) -> UiEvent

Routes a mouse gesture in document cell coordinates; visible overlays occlude the document within their bounds.

Examples found in repository

examples/chat/demo.rs (line 873)

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

pub fn handle_mouse_as_layer( &mut self, options: &OverlayOptions, viewport: Size, x: u16, y: u16, mouse: Mouse, ) -> Option<UiEvent>

Routes a viewport-coordinate mouse gesture into this tree when it is composited as a raw crate::Layer under options — the raw-frame host counterpart of the overlay stack’s own routing (crate::Renderer::present_overlaid instead of Ui::show_overlay). The band is resolved exactly as the compositor resolves it, coordinates are translated into this tree’s local cells, and a drag that started inside stays captured. None means the gesture fell outside the layer (a Move outside also clears hover chrome).

Examples found in repository

examples/chat/picker.rs (line 297)

	pub fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> PickerEvent {
		match self
			.ui
			.handle_mouse_as_layer(&self.options, viewport, col, row, kind)
		{
			Some(event) => self.route(event),
			None if kind == Mouse::Click => PickerEvent::Close,
			None => PickerEvent::Consumed,
		}
	}

examples/chat/commands.rs (line 98)

	pub fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> PaletteEvent {
		match self
			.ui
			.handle_mouse_as_layer(&self.options, viewport, col, row, kind)
		{
			Some(event) => self.route(event),
			None if kind == Mouse::Click => PaletteEvent::Close,
			None => PaletteEvent::Consumed,
		}
	}

examples/chat/sidebar.rs (line 113)

	pub fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> bool {
		if !self.open {
			return false;
		}
		if self
			.ui
			.handle_mouse_as_layer(&self.options, viewport, col, row, kind)
			.is_some()
		{
			if kind == Mouse::Click && !self.focused {
				self.focused = true;
				self.ui.focus_first();
			}
			true
		} else {
			if kind == Mouse::Click {
				self.blur();
			}
			false
		}
	}

pub fn values(&self) -> Value

Collects values from every visible component of the base tree; overlay trees report through Ui::overlay.

Examples found in repository

examples/gallery/main.rs (line 101)

fn active_tab(ui: &Ui) -> String {
	ui.values()["view"].as_str().unwrap_or_default().to_owned()
}

examples/gallery/render.rs (line 127)

pub(crate) fn sync_preview(ui: &mut Ui, synced: &mut String) {
	let text = ui.values()["src"].as_str().unwrap_or_default().to_owned();
	if text != *synced {
		ui.set_text("preview", text.clone());
		*synced = text;
	}
}

pub fn show_overlay( &mut self, root: impl IntoComponent, options: OverlayOptions, ) -> OverlayId

Stacks an overlay tree above the document.

The overlay is its own retained Ui: address it through Ui::overlay / Ui::overlay_mut for set_text, values, and friends. Placement follows options against the viewport of each Ui::present; the layer composites above the document and never enters native terminal scrollback. Explicit z orders layers regardless of creation order; later overlays stack on top among equal z. The topmost visible modal overlay receives every key and paste until closed or hidden; a non-modal layer (OverlayOptions::non_modal) leaves the keyboard with the base tree until focused through Ui::focus_overlay or a click inside its band.

Panics

Panics when called on an overlay’s own tree: overlays stack on the presenting Ui.

Examples found in repository

examples/gallery/overlay.rs (lines 36-55)

pub(crate) fn show_picker(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Switch Model">
				<col gap=1>
					<text dim>{"Session-only switch — role models stay unchanged"}</text>
					<select id=model>
						for (value, label, stats) in MODELS {
							<option value={value} desc={stats}>{label}</option>
						}
					</select>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::Center)
			.width(Dim::Pct(70))
			.min_width(48)
			.max_height(Dim::Pct(60))
			.min_viewport(Size::new(40, 8)),
	)
}

/// Opens the keybinding help layer.
pub(crate) fn show_help(ui: &mut Ui) -> OverlayId {
	ui.show_overlay(
		dom! {
			<box border=round title="Help">
				<col>
					<text>{"Ctrl+K  switch model"}</text>
					<text>{"Ctrl+G  toggle this help"}</text>
					<text>{"Esc     close top layer"}</text>
					<text>{"Ctrl+C  quit"}</text>
				</col>
			</box>
		},
		OverlayOptions::default()
			.anchor(OverlayAnchor::BottomRight)
			.width(Dim::Cells(30))
			.margin(OverlayMargin::uniform(1)),
	)
}

pub fn close_overlay(&mut self, id: OverlayId) -> bool

Removes an overlay; the next present repaints the document beneath it.

Returns false for an unknown id.

Examples found in repository

examples/gallery/main.rs (line 155)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.quit([Key::Ctrl('c'), Key::Ctrl('q')])
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	// The picker tab opens with the first model's details, like the chat
	// overlay does.
	picker::show_detail_on(app.ui_mut(), Some(0));

	let mut synced = String::new();
	let mut lab = anim::Lab::new();
	let mut layers = Layers::default();
	let mut next_step = tokio::time::Instant::now() + anim::AUTOPLAY_STEP;

	loop {
		let event = tokio::select! {
			event = app.next() => match event? {
				Some(event) => event,
				None => break,
			},
			() = tokio::time::sleep_until(next_step) => {
				if lab.autoplay && active_tab(app.ui()) == "Anim" {
					lab.advance(app.ui_mut());
				}
				next_step += anim::AUTOPLAY_STEP;
				continue;
			},
		};
		match event {
			AppEvent::Resized(viewport) => {
				for pane in render::PANE_IDS {
					app.ui_mut().set_height(pane, render::pane_height(viewport));
				}
			},
			AppEvent::Key(key) => match active_tab(app.ui()).as_str() {
				"Anim" => lab.handle_key(key, app.ui_mut()),
				"Overlay" => match key {
					Key::Ctrl('k') if layers.picker.is_none() => {
						layers.picker = Some(overlay::show_picker(app.ui_mut()));
					},
					Key::Ctrl('g') => match layers.help.take() {
						Some(id) => {
							app.ui_mut().close_overlay(id);
						},
						None => layers.help = Some(overlay::show_help(app.ui_mut())),
					},
					_ => {},
				},
				_ => {},
			},
			// The Overlay tab's modal select committed a model.
			AppEvent::Changed { id, value } if id == "model" => {
				if let Some(overlay) = layers.picker.take() {
					let label = overlay::MODELS
						.iter()
						.find(|(short, ..)| *short == value)
						.map_or(value.as_str(), |(_, label, _)| label);
					app.ui_mut().set_text("status", format!("model: {label}"));
					app.ui_mut().close_overlay(overlay);
				}
			},
			// The Picker tab's select moved: mirror the chat picker's
			// facts-and-chips detail line.
			AppEvent::Highlighted { id, value } if id == "models" => {
				picker::show_detail_on(app.ui_mut(), value.as_str().parse().ok());
			},
			AppEvent::Filtered { id, value, .. } if id == "models" => {
				let model = value.and_then(|value| value.as_str().parse().ok());
				picker::show_detail_on(app.ui_mut(), model);
			},
			AppEvent::OverlayClosed(id) => {
				if layers.picker == Some(id) {
					layers.picker = None;
				}
				if layers.help == Some(id) {
					layers.help = None;
				}
			},
			_ => {},
		}
		render::sync_preview(app.ui_mut(), &mut synced);
		// Reserve the Overlay tab's chords only while it is showing, so the
		// focused composer can't spend Ctrl+K on kill-line — and the Live
		// tab's editor keeps it.
		let chords: &[Key] = if active_tab(app.ui()) == "Overlay" {
			&[Key::Ctrl('k'), Key::Ctrl('g')]
		} else {
			&[]
		};
		app.set_hotkeys(chords.iter().copied());
	}
	Ok(())
}

pub fn close_top_overlay(&mut self) -> Option<OverlayId>

Removes the topmost layer (highest z, most recent among ties), if any.

This pops the stack regardless of modality; for dismissing the layer that emitted a UiEvent::Cancel, use Ui::close_active_overlay — the stack top may be a non-modal pane sitting above the modal that routed the key.

pub fn close_active_overlay(&mut self) -> Option<OverlayId>

Closes the layer currently receiving keys — the topmost visible modal overlay, else the focused non-modal pane — returning its id.

The manual-host counterpart of the crate::App cancel policy: after a UiEvent::Cancel surfaces from the overlay stack, this dismisses the layer that emitted it, even when a higher-z non-modal pane stacks above it.

pub fn set_overlay_hidden(&mut self, id: OverlayId, hidden: bool) -> bool

Temporarily hides or reshows an overlay without discarding its state.

Hiding the layer holding the keyboard returns keys to the base tree. Returns false for an unknown id.

pub fn overlay_hidden(&self, id: OverlayId) -> Option<bool>

Whether an overlay is temporarily hidden; None for an unknown id.

pub fn overlay(&self, id: OverlayId) -> Option<&Self>

Borrows an overlay’s retained tree.

pub fn overlay_mut(&mut self, id: OverlayId) -> Option<&mut Self>

Mutably borrows an overlay’s retained tree for set_text and friends.

pub fn has_overlay(&self) -> bool

Whether any modal overlay is currently visible (not hidden or gated).

While one is, crate::App holds the terminal’s alternate screen (vim/less idiom): the whole composited viewport paints there with mouse tracking active, and the untouched main screen restores when the last visible modal overlay closes. Non-modal layers never hold: they composite into the live inline viewport while the document keeps committing to native scrollback beneath them.

pub fn top_overlay(&self) -> Option<OverlayId>

Identity of the layer receiving keys — the topmost visible modal overlay, else the focused non-modal layer.

pub fn focus_overlay(&mut self, id: OverlayId) -> bool

Directs keys and paste to a layer until it is blurred, closed, or hidden, or a modal overlay opens above it.

The layer’s focus ring activates so its chrome shows where typing lands. Intended for non-modal layers — a modal overlay already captures the keyboard while topmost. Returns false for an unknown id.

pub fn blur_overlay(&mut self) -> Option<OverlayId>

Returns the keyboard to the base tree, clearing the previously focused layer’s own focus so no stale chrome (or hardware caret) suggests typing still lands there. Returns the layer that had key focus.

pub const fn focused_overlay(&self) -> Option<OverlayId>

The non-modal layer holding the keyboard through Ui::focus_overlay or a click, if any.