//! 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;