Files
luxe/crates/luxe-tui/src/glyphs.rs
Evan Whittaker 09a7de2520 Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
2026-10-17 12:08:30 -05:00

481 lines
22 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! glyphs — the icon vocabulary, at three fidelities.
//!
//! Every icon in the TUI is decoration: the words beside it carry the meaning, and a reader whose
//! font has none of these should lose shine, not information, and never meet a `□` for an icon.
//!
//! So each icon is declared once in the `icons!` table below, by *meaning*, with all three of its
//! renderings beside it:
//!
//! - [`GlyphTier::Nerd`] — Material Design icons from a patched font, the look Luxe ships with.
//! - [`GlyphTier::Unicode`] — Geometric Shapes, Arrows and two Dingbats: no private use anywhere,
//! nothing newer than Unicode 1.1 outside a couple of shapes, and every entry one cell wide.
//! - [`GlyphTier::Ascii`] — plain punctuation, for SSH into a minimal box, a CI log, or a terminal
//! whose `LANG` is not UTF-8.
//!
//! # Some icons simply go away
//!
//! A fallback shape is only worth drawing where it still tells a reader something. On a tool card it
//! does not: the tool's name is right there in bold, and the card's color and wash already say how the
//! call went — the icon is the bonus, so below the nerd tier it is **omitted** rather than approximated.
//! An empty rendering means exactly that, and [`Icon::prefix`] drops the separator with it so the name
//! sits where it should instead of behind a stray space.
//!
//! # Why the other fallbacks share shapes
//!
//! The nerd tier gives every surface its own silhouette. There is no honest way to reproduce that
//! with shapes a bare font is guaranteed to have, so the fallbacks group by *family* instead — one
//! shape for browsers, one for documents, one for attention, one per tool category. A reader still
//! sorts "file operation" from "search" from "web" at a glance, and the label settles the rest.
//!
//! # Width
//!
//! The trap is not availability, it is width. A private-use icon is one cell; the obvious substitutes
//! often are not — `⚙` and much of Miscellaneous Symbols take emoji presentation in many fonts
//! and render two cells wide, which shears every row they sit in. Hence the narrow palette, and hence
//! the test that measures all three renderings of every icon.
//!
//! Advance width is not the whole story, though. A Nerd Font ships two cuts of every face: the
//! `Mono` one rescales each icon into a single cell, while the other leaves it at its drawn size
//! (up to twice the cell) behind the same one-cell advance, so the icon paints over the space after
//! it. Nothing a terminal reports tells the two apart, so [`GlyphTier::NerdWide`] is the reader's
//! answer: the same shapes, given the second cell they were drawn for. [`icon_gap`] is the one
//! place that decides how much room that is, and every surface goes through it.
//!
//! It applies to **this vocabulary only**. The rest of what the TUI draws — a `✓` on a finished
//! todo, the `▸` on a folded run, the arrows in a token count, the half blocks the slabs are cut
//! with — is ordinary text at ordinary width, and widening it would only push it away from what it
//! labels. A row that reaches for [`icon_prefix`] with a marker of its own is the mistake to watch
//! for.
//!
//! # The spinner asks a different question
//!
//! [`spinner`] sits outside the table on purpose. The table asks *does the terminal's own face
//! contain this*, which is what a mark other columns align to has to answer. A spinner is one cell
//! with nothing aligned to it, so it may come from a fallback font, and braille usually does. So it
//! is measured rather than assumed (`braille_available`) and draws the ten-frame sweep where a font
//! on the machine has it, block elements where none does, and ASCII where the tier says to assume
//! nothing. Three drawings is too many for anything the reader has to *read*; this one they only
//! have to see move.
mod detect;
mod format;
mod spinner;
mod state;
pub use format::{configured_glyph, icon_cells, icon_gap, icon_label, icon_prefix};
pub use spinner::spinner;
#[cfg(test)]
pub(crate) use spinner::spinner_ticks_per_frame;
pub use state::{braille, resolve_vocabulary, set_braille, set_tier, tier};
use unicode_width::UnicodeWidthStr;
#[cfg(test)]
use {
detect::braille_drawable,
luxe_core::config::GlyphStyle,
spinner::{SPINNER_ASCII, SPINNER_BLOCKS, SPINNER_BLOCK_TICKS, SPINNER_BRAILLE},
};
/// How much glyph fidelity the terminal and font can be asked for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum GlyphTier {
/// Material Design icons from a Nerd Font.
#[default]
Nerd,
/// The same icons, from a face that draws them two cells wide.
NerdWide,
/// Geometric Shapes and Arrows; no private-use codepoints.
Unicode,
/// Plain ASCII punctuation.
Ascii,
}
/// Declares the icon vocabulary: what each icon means, then its three drawings.
///
/// The enum, [`Icon::renderings`] and [`EVERY_ICON`] all come out of this one list, which is what
/// makes the claim above true — an icon really is declared once, by meaning, with its renderings
/// beside it, rather than spelled out in three places that have to agree.
///
/// They were three places, and a hand-kept list can only fail in one direction: *removing* an icon
/// breaks the enum, the match and the array, so the compiler walks you through all three, while
/// *adding* one breaks only two. `Changes` went in that way and sat outside [`EVERY_ICON`] — and so
/// outside every check that its fallbacks are one cell wide, free of private-use codepoints and
/// actually ASCII — for its whole existence.
macro_rules! icons {
($( $(#[$meaning:meta])* $name:ident => [$nerd:expr, $unicode:expr, $ascii:expr] ),+ $(,)?) => {
/// Every icon the TUI can draw, named for what it means rather than what it looks like.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Icon {
$( $(#[$meaning])* $name, )+
}
impl Icon {
/// This icon's three renderings: `[nerd, unicode, ascii]`.
///
/// One exhaustive match, so a new icon cannot be added without deciding what a bare
/// terminal shows for it — the declaration asks.
const fn renderings(self) -> [&'static str; 3] {
match self {
$( Self::$name => [$nerd, $unicode, $ascii], )+
}
}
}
/// Every icon, for the table tests and any surface that wants to enumerate them.
///
/// Generated from the list above, so it cannot fall behind it.
pub const EVERY_ICON: &[Icon] = &[$( Icon::$name, )+];
};
}
icons! {
// === Surfaces (a bordered panel or overlay) ===
/// Fuzzy command search — the command palette
Palette => ["\u{f0349}", "■", "*"],
/// Slash-command completion above the composer
SlashMenu => ["\u{f07b7}", "►", ">"],
/// `@`-mention file completion, and a file generally
FileMenu => ["\u{f0214}", "▪", "#"],
/// Session history browser
Session => ["\u{f02da}", "■", "~"],
/// Find-in-transcript bar
Search => ["\u{f13b8}", "○", "/"],
/// Keybinding cheat sheet
Help => ["\u{f030c}", "■", "?"],
/// Review chapter outline
Outline => ["\u{f0279}", "≡", "="],
/// Review findings list
Findings => ["\u{f023b}", "▲", "!"],
/// Review finding detail / evidence
Evidence => ["\u{f02fc}", "●", "i"],
/// Review finding composer
Compose => ["\u{f03eb}", "►", "+"],
/// Review source (working tree, turn, base, commit)
Source => ["\u{f0718}", "└", "^"],
/// Finish/accept a review
Finish => ["\u{f012c}", "■", "v"],
// === Attention (something is waiting on the reader) ===
/// Tool-permission request
Permission => ["\u{f0483}", "▲", "!"],
/// Agent question addressed to the user
Question => ["\u{f0625}", "▲", "?"],
/// Provider sign-in (the login wizard)
Key => ["\u{f0306}", "●", "@"],
/// A submission handed to the running turn
Steering => ["\u{f0054}", "→", ">"],
/// A submission waiting for a turn of its own
Queued => ["\u{f03e4}", "▪", "."],
/// A submission that never ran
NeverSent => ["\u{f0156}", "×", "x"],
// === The model ===
/// A language model (catalog, statusline, dock)
Model => ["\u{f06a9}", "●", "%"],
/// Model reasoning
Thinking => ["\u{f0335}", "●", "~"],
// === Dashboard menu ===
Find => ["\u{f021e}", "○", "/"],
NewSession => ["\u{f0214}", "►", "+"],
Grep => ["\u{f0284}", "○", "/"],
Config => ["\u{f0493}", "■", "="],
Quit => ["\u{f05fc}", "×", "x"],
/// The project's context as a whole, and the list that shows all of it
Loaded => ["\u{f03d6}", "▪", "#"],
ContextFile => ["\u{f0219}", "▪", "#"],
/// Codicons' own MCP mark, rather than a puzzle piece `activate_tools` already wears
Mcp => ["\u{ec47}", "□", "&"],
Skill => ["\u{f140b}", "§", "*"],
SessionEntry => ["\u{f028c}", "■", "~"],
// === Statusline ===
Branch => ["\u{f062c}", "└", "^"],
/// The branch's pull request
PullRequest => ["\u{f04c2}", "↑", "^"],
/// An issue, beside its number in `/github` (`oct-issue_opened`)
Issue => ["\u{f41b}", "○", "o"],
/// `/github`'s pull requests waiting on your review (`md-eye_outline`)
ReviewRequested => ["\u{f06d0}", "○", "o"],
/// `/github`'s pull requests you opened (`md-account_outline`)
Mine => ["\u{f0013}", "●", "@"],
/// A pull request's or an issue's Overview tab (`oct-info`)
Overview => ["\u{f449}", "≡", "="],
/// A pull request's or an issue's Conversation tab (`md-comment_multiple_outline`)
Conversation => ["\u{f0181}", "»", "\""],
/// A review that only comments, as GitHub's own review dialog draws it (`oct-comment`)
ReviewComment => ["\u{f41f}", "»", "\""],
/// A review that approves (`oct-check`)
ReviewApprove => ["\u{f42e}", "•", "+"],
/// A review that requests changes (`oct-file_diff`)
ReviewRequestChanges => ["\u{f4d2}", "±", "!"],
/// GitHub itself: `/github`, and the surfaces that post to it, open on it or read from it
/// (`md-github`)
GitHub => ["\u{f02a4}", "●", "*"],
Folder => ["\u{f024b}", "■", "/"],
Context => ["\u{f0e4}", "▪", "#"],
/// How far the session's checklist has got
Plan => ["\u{f08a8}", "≡", "="],
/// Files this session has changed
Changes => ["\u{f440}", "±", "+"],
// === Modes, on the composer's title ===
/// Plan mode: reads, asks, writes only the plan (`md-clipboard_text_outline`). Hollow where
/// build is solid, for a terminal with no icon font: a sketch, then the thing.
ModePlan => ["\u{f0a38}", "○", ""],
/// Build mode, the default: changes files and runs commands (`md-hammer_wrench`)
ModeBuild => ["\u{f1323}", "●", ""],
// === Inline in the transcript and composer ===
/// The `@` picker, which references files and GitHub (`md-at`)
Mention => ["\u{f0065}", "@", "@"],
/// A mention source of the reader's own, when it names no icon (`md-tag_outline`)
MentionSource => ["\u{f04fc}", "▪", "-"],
/// An attached file on a submission
Attachment => ["\u{f0c6}", "▪", "#"],
/// An attached image
Image => ["\u{f03e}", "▫", "&"],
/// The copy affordance on a code block
Copy => ["\u{f0c5}", "▪", "c"],
/// A fenced code block whose language has no mark of its own
Code => ["\u{f0174}", "", ""],
// === Markdown alerts (`> [!NOTE]` and its four siblings) ===
//
// Five silhouettes a reader can tell apart at a terminal's glyph size, which rules out the
// ornate ones: an `i` in a circle, a bulb, and the exclamation mark in a circle, a triangle
// and an octagon — the shapes road signs already spend on the same three severities.
// Codepoints confirmed by glyph *name* in IosevkaTermNerdFontMono (`md-alert_octagon`, not a
// plausible-looking neighbor) at one cell of advance.
//
// Below the nerd tier they collapse into the two families the rest of the table uses — `●`/`○`
// for something worth knowing, `▲` for something worth stopping at — because the alert's word
// is written out beside every one of them and carries the distinction on its own.
/// A `> [!NOTE]` alert
AlertNote => ["\u{f02fd}", "●", "i"],
/// A `> [!TIP]` alert
AlertTip => ["\u{f0336}", "○", "*"],
/// A `> [!IMPORTANT]` alert
AlertImportant => ["\u{f0028}", "▲", "!"],
/// A `> [!WARNING]` alert
AlertWarning => ["\u{f0026}", "▲", "!"],
/// A `> [!CAUTION]` alert
AlertCaution => ["\u{f0029}", "▲", "!"],
// === Languages (a fenced code block's own mark) ===
//
// Brand marks, one per language, drawn only at the nerd tier: the language's *name* is written
// beside them on the same rule, so a terminal without a patched font loses the shine and keeps
// the information. Substituting a geometric shape would be worse than nothing — twenty-seven
// languages cannot have twenty-seven honest shapes in a bare font, and one `▪` for all of them
// says less than the word already does.
//
// Every codepoint below was verified present in IosevkaTermNerdFontMono and confirmed by its
// glyph *name* (`dev-rust`, `seti-typescript`, …) rather than by memory: `U+E60B` looks like a
// plausible JSON mark and is `seti-less`.
LangRust => ["\u{e7a8}", "", ""],
LangPython => ["\u{e73c}", "", ""],
LangTypeScript => ["\u{e628}", "", ""],
LangJavaScript => ["\u{e781}", "", ""],
LangGo => ["\u{e626}", "", ""],
// `seti-c` and `seti-cpp` rather than the `custom-*` pair: those two are both a letter in a
// circle and at a terminal's glyph size they are the same picture, which defeats the only
// reason to spend a cell on a mark. These read as `C` and `C+`.
LangC => ["\u{e649}", "", ""],
LangCpp => ["\u{e646}", "", ""],
LangShell => ["\u{e760}", "", ""],
LangRuby => ["\u{e739}", "", ""],
LangLua => ["\u{e826}", "", ""],
LangSvelte => ["\u{e8b7}", "", ""],
LangJson => ["\u{e80b}", "", ""],
LangYaml => ["\u{e8eb}", "", ""],
LangToml => ["\u{e6b2}", "", ""],
LangHtml => ["\u{e736}", "", ""],
LangCss => ["\u{e749}", "", ""],
LangSql => ["\u{e706}", "", ""],
LangMarkdown => ["\u{e73e}", "", ""],
LangJava => ["\u{e738}", "", ""],
LangPhp => ["\u{e73d}", "", ""],
LangSwift => ["\u{e755}", "", ""],
LangKotlin => ["\u{e81b}", "", ""],
LangHaskell => ["\u{e777}", "", ""],
LangZig => ["\u{e8ef}", "", ""],
LangNix => ["\u{e843}", "", ""],
LangDocker => ["\u{e7b0}", "", ""],
LangDiff => ["\u{eae1}", "", ""],
/// A tool's raw output, in the transcript
ToolOutput => ["\u{f07e}", "▎", "|"],
/// A system notice in the transcript
SystemLine => ["\u{f120}", "└", "^"],
/// An answer the reader gave the agent, on the card that asked for it. Drawn at every tier
/// rather than omitted like a tool card's icon, because this row is aligned against the header
/// above it — whose tool is `question`, which wears [`Icon::Question`] and keeps its fallbacks.
/// Drop these and the two labels shear apart on any terminal without the Material shapes.
Answer => ["\u{f012c}", "■", "v"],
// === Tools: file operations ===
ToolRead => ["\u{edfa}", "", ""],
ToolWrite => ["\u{f0193}", "", ""],
ToolEdit => ["\u{f440}", "", ""],
// === Tools: the shell ===
ToolBash => ["\u{f07b7}", "", ""],
// === Tools: search ===
ToolGrep => ["\u{f0451}", "", ""],
ToolGlob => ["\u{f021e}", "", ""],
ToolAstGrep => ["\u{f0169}", "", ""],
ToolSymbolSearch => ["\u{f1907}", "", ""],
// === Tools: code intelligence ===
ToolDiagnostics => ["\u{ea6c}", "", ""],
ToolNavigation => ["\u{f018b}", "", ""],
ToolModuleReport => ["\u{f04aa}", "", ""],
ToolReadSymbol => ["\u{f0295}", "", ""],
ToolImpact => ["\u{f1049}", "", ""],
ToolDebug => ["\u{f00e4}", "", ""],
// === Tools: the project ===
ToolGit => ["\u{f02a2}", "", ""],
ToolTest => ["\u{f0668}", "", ""],
// === Tools: the web ===
ToolWebFetch => ["\u{f059f}", "", ""],
ToolWebSearch => ["\u{f070f}", "", ""],
// === Tools: session and loop ===
ToolTodo => ["\u{f0135}", "", ""],
ToolSkill => ["\u{f51b}", "", ""],
ToolScreenshot => ["\u{f0100}", "", ""],
ToolLoopControl => ["\u{f0456}", "", ""],
ToolMcp => ["\u{f06a5}", "", ""],
ToolActivate => ["\u{f0431}", "", ""],
/// Any tool with no icon of its own
ToolGeneric => ["\u{f05b7}", "", ""],
}
/// Declares the structural marks: the glyphs a row is *built* from rather than labeled with.
///
/// Same three renderings as [`icons!`], one rule different — a mark may never be empty. An icon is
/// decoration and can stand down, which is why two dozen of them do; a fold arrow, a cursor or a
/// tree corner is the thing the row is saying, and dropping it would cost meaning rather than
/// shine.
macro_rules! marks {
($( $(#[$meaning:meta])* $name:ident => [$nerd:expr, $unicode:expr, $ascii:expr] ),+ $(,)?) => {
/// A structural glyph: part of a row's grammar, not an icon beside its label.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Mark {
$( $(#[$meaning])* $name, )+
}
impl Mark {
/// This mark's three renderings: `[nerd, unicode, ascii]`.
const fn renderings(self) -> [&'static str; 3] {
match self {
$( Self::$name => [$nerd, $unicode, $ascii], )+
}
}
}
/// Every mark, for the table tests.
pub const EVERY_MARK: &[Mark] = &[$( Mark::$name, )+];
};
}
marks! {
/// The row under the cursor, in a menu or a picker
Cursor => ["\u{276f}", "\u{203a}", ">"],
/// A run that is folded shut
FoldClosed => ["\u{25b8}", "\u{25ba}", ">"],
/// A run that is open
FoldOpen => ["\u{25be}", "\u{25bc}", "v"],
/// A row wrapped from the one above it
Continuation => ["\u{21b3}", "\u{2514}", "\\"],
/// Lines the card is not showing
Elision => ["\u{22ef}", "\u{2026}", "."],
/// Input served from the prompt cache
CacheReuse => ["\u{21ba}", "\u{2190}", "<"],
/// Work that stopped before it finished — a cancelled call, a blocked task
Halted => ["\u{2298}", "\u{25cb}", "-"],
/// Work under way, where a spinner would be too loud
Underway => ["\u{25c9}", "\u{25cf}", "*"],
/// Present, installed, checked
Yes => ["\u{2713}", "\u{25a0}", "v"],
/// Absent, missing, unchecked
No => ["\u{2717}", "\u{00d7}", "x"],
/// Waiting on something else to finish, or on someone else
Waiting => ["\u{25d4}", "\u{25cb}", "o"],
}
impl Mark {
/// This mark at `tier`. Pure, so tests never depend on process state.
pub fn at(self, tier: GlyphTier) -> &'static str {
let [nerd, unicode, ascii] = self.renderings();
match tier {
GlyphTier::Nerd | GlyphTier::NerdWide => nerd,
GlyphTier::Unicode => unicode,
GlyphTier::Ascii => ascii,
}
}
/// This mark at the tier the process resolved at startup.
pub fn glyph(self) -> &'static str {
self.at(tier())
}
/// Whether `text` begins with any of this mark's renderings.
///
/// A few surfaces stamp a mark into a string and re-read it later. The tier can move between
/// those two moments, so the check has to accept every rendering.
pub fn leads(self, text: &str) -> bool {
self.renderings().iter().any(|glyph| text.starts_with(glyph))
}
/// This mark and the space after it, or the same width in blanks when `shown` is false.
///
/// The `❯ label` / ` label` pair that a dozen pickers spelled out by hand. One owner,
/// because the invariant is easy to state and easy to break: an unselected row spends the
/// gutter too, or every label steps sideways as the cursor lands on it.
pub fn gutter(self, shown: bool) -> String {
if shown {
format!("{} ", self.glyph())
} else {
" ".repeat(UnicodeWidthStr::width(self.glyph()) + 1)
}
}
}
impl std::fmt::Display for Mark {
/// So a mark drops into `format!` where a literal would sit.
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.glyph())
}
}
impl Icon {
/// This icon at `tier`. Pure, so tests never depend on process state.
pub fn at(self, tier: GlyphTier) -> &'static str {
let [nerd, unicode, ascii] = self.renderings();
match tier {
GlyphTier::Nerd | GlyphTier::NerdWide => nerd,
GlyphTier::Unicode => unicode,
GlyphTier::Ascii => ascii,
}
}
/// This icon and the clearance after it, or nothing at all when it has no rendering at this tier.
///
/// For the `{icon} {label}` shape that most surfaces use: an omitted icon has to take its separator
/// with it, or the label sits one column in from where it belongs.
pub fn prefix(self) -> String {
icon_prefix(self.glyph())
}
/// Whether `text` begins with any of this icon's renderings.
///
/// A couple of surfaces stamp an icon into a string and re-read it later to recover what the
/// string described. The tier can move between those two moments — a `/reload` is enough — so the
/// check has to accept every rendering rather than the one that happens to be current.
pub fn leads(self, text: &str) -> bool {
self.renderings().iter().any(|glyph| text.starts_with(glyph))
}
/// This icon at the tier the process resolved at startup.
///
/// The vocabulary is a property of the terminal and the config, so it is process-wide rather than
/// threaded through every view signature; `/reload` can move it, which is why it is an atomic
/// rather than a `OnceLock`.
pub fn glyph(self) -> &'static str {
self.at(tier())
}
}
#[cfg(test)]
mod tests;