Glyph loader
Fourteen text-glyph loaders (braille, sand, blocks, scanner…) that settle into a check, a warning or a cross when the agent finishes, waits or fails. One table each, phase-locked to a shared clock.
oxyn add glyph-loaderrsx! {
GlyphLoader {
state: agent.state(),
now: clock.now() // one shared clock keeps every loader in phase,
size: 18.0,
}
}Rendered from Rust at build time · goes live when visible
When to use
- Glyph loaders are the spinner that sits left of a status line in a terminal or an IDE panel: ⠹ Thinking · 12s.
- They are the cheapest loader we ship (text only, a frame every 80–600 ms), they work on every surface including Terminal, and they fit inside running text at 12–16 px.
- Coding agents use them everywhere: braille at 80 ms in OpenCode, Kilo and MonoCode, braille at 100 ms in Codex and Zed, a mirrored star glyph at 120 ms in Claude Code (research note 08).
When not to use
- The prompt box for an agent, in six layouts: use Composer instead.
- Send, stop, queue and steer in one control, in twelve styles: use Send control instead.
- A dot and a label for any of the 13 agent states, as a pill, inline or a dot alone: use Status indicator instead.
Installation
Glyph loader is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add glyph-loaderuse crate::oxyn::{GlyphLoader, GLYPH_LOADER_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{GlyphLoader, GLYPH_LOADER_CSS};
Usage
rsx! {
GlyphLoader {
state: agent.state(),
now: clock.now() // one shared clock keeps every loader in phase,
size: 18.0,
}
}Examples
Glyph braille
The default spinner.
Code
rsx! {
GlyphLoader {
state: agent.state(),
now: clock.now() // one shared clock keeps every loader in phase,
size: 18.0,
}
}Glyph scanner
A scanning bar for IDE status rows.
Code
rsx! {
GlyphLoader {
state: agent.state(),
now: clock.now() // one shared clock keeps every loader in phase,
variant: "glyph-scanner",
size: 18.0,
}
}Glyph sand
An hourglass of dots.
Code
rsx! {
GlyphLoader {
state: agent.state(),
now: clock.now() // one shared clock keeps every loader in phase,
variant: "glyph-sand",
size: 18.0,
}
}All states
All 14 in the waiting state.
Code
rsx! {
GlyphLoader {
state: agent.state(),
now: clock.now() // one shared clock keeps every loader in phase,
size: 18.0,
}
}API reference
GlyphLoader
| Prop | Type | Default | Description |
|---|---|---|---|
staterequired | AgentState | — | The agent state. |
nowrequired | ClockMs | — | Shared clock time. |
variant | String | "glyph-braille" | Variant id (`glyph-braille`, `loader/glyph-sand`, …). Unknown ids fall back to braille. |
still | bool | Default::default() | Draw still frames (reduced motion, mirrored loader, poster). |
size | f32 | 13.0 | Font size in px. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| — | Not focusable |
Accessibility
- The glyphs are aria-hidden; pair it with status text (or a StatusIndicator) that names the state.
- still draws one frame for reduced motion and posters.
From the spec
- The glyph is decorative:
aria-hidden="true"in Dioxus, not exposed as an accessible node in GPUI, excluded from selection. The host row carries the label ("Thinking, 12 seconds"). aria-busy="true"is set on the content being produced (message, tool card) by the host, removed on Done / Failed / Cancelled.- No live-region output from the loader. Phase announcements come from the composer's single polite live region (loaders.md §8); waiting and failed are assertive there.
- Flashing: the fastest table (
glyph-scanner, 50 ms) moves a small glyph; it does not flash an area. Whole-glyph on/off blinks are limited to ≤ 3 per second (glyph-bulletis 0.84 Hz;glyph-heartbeatbeats twice per 1.6 s cycle). - Reduced motion /
prefers-reduced-motion: still glyph per phase (§3); cycling stops. - Contrast: glyph colour ≥ 3:1 against the row background in every phase including the stall ramp midpoint;
◌dim state still ≥ 3:1 (dim via weight, not alpha below 0.6). - Not colour alone: waiting changes the glyph (sand), stalled hard changes to
◌plus text, done/failed change to✓/✕.
Motion & interaction
- Enter. A glyph can't scale cleanly, so enter is an opacity fade 0 → 1 over 120 ms (
dur.fast), starting on the frame the clock dictates (never frame 0 by default). - Submitted pulse. One bright frame dimming over 400 ms; the loop starts only when
Thinkingarrives, so a quick answer shows no spinner at all. - Phase change. Tables swap on the next frame boundary (never mid-frame); colour lerps in OKLab over 400 ms. Thinking → Waiting changes both table and colour, so human-blocked reads differently from generating (Zed swaps Dots for Sand for this; research note 08).
- Multi-cell trails. Per-cell brightness levels
0.3 + 0.7 × level(OpenCode's ramp, research note 08) for scanners, waves and rain; implemented as per-cell alpha on one colour. - Holds. Tables may hold a frame for several ticks (
holds) to give a beat: fill/drain holds at the top and bottom, double-beat rests, the scanner pauses at each end. - Stall. Frame ms doubles over the 2 s ramp (eased via the phase integral, no stutter); colour ramps toward
warn. Atstall_hardthe glyph stops on◌. The first event snaps back in 200 ms. - Done. The current frame is replaced by
✓with a 120 ms fade; the host line rolls to past tense ("Worked for 42s", family C). Failed:✕+ the host shakes, not the glyph. - Hover (only when the host row is hoverable): tooltip "Thinking · 42 s"; the glyph doesn't change.
Timing
5.1 Free frame tables
| Variant | Frames (one cell unless noted) | Frame ms | Loop | Notes | |
|---|---|---|---|---|---|
loader/glyph-braille | ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏ | 80 | 800 ms | the common braille set (cli-spinners, OpenCode at 80 ms; Codex, Zed at 100 ms) | |
loader/glyph-sand | ⠛ ⠫ ⡋ ⡍ ⣉ ⣅ ⣤ ⣤ ⣄ ⣀ ⡀ ⠀ (own sequence) | 150, holds [1,1,1,1,1,1,2,1,1,1,1,1] | 1950 ms | grains fall top → bottom, then drain; default waiting table; authored for Oxyn, not Zed's 35-frame Sand | |
loader/glyph-block | 3 cells: ░░░ ▒░░ ▓▒░ █▓▒ ▓█▓ ▒▓█ ░▒▓ ░░▒ | 100 | 800 ms | shade wave; width-unsafe on ambiguous-wide terminals (§7) | |
loader/glyph-bar | ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▇ ▆ ▅ ▄ ▃ ▂ | 80, holds [2,2,1,1,1,1,1,2,1,1,1,1,1,2] | 1440 ms | fill / drain (OpenCode table, MIT) | |
loader/glyph-dots | 3 cells: · ·· ··· ·· · (padded) | 180 | 1080 ms | ellipsis that travels, not a typing bounce | |
loader/glyph-line | `\ | / - \` (ASCII) | 100 | 400 ms | universal fallback; terminal minimum |
loader/glyph-arc | ◜ ◠ ◝ ◞ ◡ ◟ | 100 | 600 ms | arc travelling round a circle | |
loader/glyph-quadrant | ◰ ◳ ◲ ◱ | 160 | 640 ms | corner orbit (OpenCode, MIT) | |
loader/glyph-bloom | ▫ ▪ ▣ ■ ▣ ▪ | 120 | 720 ms | inset bloom (OpenCode, MIT) | |
loader/glyph-half | ◐ ◓ ◑ ◒ | 150 | 600 ms | half-disc rotation (proposed timing) | |
loader/glyph-bullet | • ↔ ◦ (dim) | 600 | 1200 ms | Codex's exec blink; calmest option; ≤ 0.84 Hz | |
loader/glyph-scanner | 8 cells, head ■, trail ▪ ▪ · at levels 1/0.6/0.35/0.15, inactive · at 0.1 | 50, holds 6 at each end | ≈ 1.3 s there and back | own values; idea from OpenCode's 8-wide scanner (holds 30 / 9 frames there) | |
loader/glyph-spark | · ⋆ ✧ ✦ ✧ ⋆ (own set, ping-pong) | 110 | 660 ms | Oxyn's breathing star; the mirrored-breath *idea* is Claude Code's, the glyphs and timing are ours | |
loader/glyph-pulse | ● brightness 0.3 + 0.7 × (cos + 1) / 2 | brightness at ≤ 20 fps | 1600 ms | seed breathe (idea from OpenCode's one-cell gallery) |
5.2 Transition timing
| Transition | Duration | Easing | Notes |
|---|---|---|---|
| Enter fade | 120 ms (dur.fast) | ease.out | starts on the clock's frame |
| Submitted dim | 400 ms × 1 | ease.out | no cycling |
| Table swap (phase change) | next frame boundary | step | never mid-frame |
| Colour lerp (phase change) | 400 ms | OKLab linear | |
| Thinking → Working tempo | 400 ms | ease.in-out on speed | frame ms ÷ 1.25 |
| Streaming tempo | 400 ms | ease.in-out | frame ms ÷ 0.6 |
| Stall soft (frame ms × 2 + colour) | 2000 ms | linear | |
Stall hard → still ◌ | next frame boundary | step | |
| Recovery snap | 200 ms | ease.out | |
Done ✓ fade-in / hold / clear | 120 / 600 / 160 ms | ease.out / — / ease.in | |
| Cancelled dim → clear | 160 ms | ease.in | |
| Reduced motion | still glyph per phase; swaps are 0–80 ms crossfades; no cycling, no brightness breathe | — | opt-in SlowFade: 2 s opacity 1 ↔ 0.6 |
Frame rate rule: glyph loaders repaint only at frame boundaries (12.5 Hz for 80 ms tables, 1.7 Hz for glyph-bullet). The glyph-pulse brightness loop is capped at 20 fps (proposed).
Responsive behaviour
- Text-sized: scales with font size and sits on the text baseline.
Edge cases (spec)
- Width stability (the main rule). At build,
xtask build-registrymeasures every frame withunicode-widthand rejects tables whose frames differ in cell count, contain emoji presentation selectors, ZWJ sequences or combining marks. Blank cells are real spaces (or⠀U+2800 in braille tables) and are never trimmed. - East Asian Ambiguous width. Several block and geometric glyphs (e.g.
░▒▓█) are ambiguous width and render two cells wide in terminals set to ambiguous = wide (common in CJK locales). Tables carrywidth_safe: bool; on a terminal with ambiguous-wide (configurable on ourTerminalsurface, since it can't always be detected), width-unsafe tables fall back toglyph-braille(braille patterns are not ambiguous width). - Monospace alignment in the GUI. The loader box is
cells × advance("0")of the mono font at the loader size, glyph centred horizontally, aligned to the label's baseline (braille sits high in most fonts: optical offset +0.05 em, proposed, per font in tokens). If a glyph's advance exceeds its cell (fallback font), it is scaled down to fit rather than pushing the label. - Missing glyphs / font fallback. At mount the renderer checks the font chain covers every frame; if not, it uses the table's
fallback(chain ends atglyph-line). In a terminal we can't check coverage, soTerminalsurface defaults to braille or ASCII tables unless the app opts in. - Long labels / overflow. The label truncates with an ellipsis; the loader box never shrinks. Multi-cell tables (scanner, waves) collapse to their one-cell fallback when the row is narrower than 24 cells (proposed).
- RTL. The glyph sits at the inline start (right). Rotating tables are unchanged; directional tables (scanner, dots, waves, handoff, chevrons) play mirrored frames generated at build.
- Tiny sizes (12 px). One-cell tables only; brightness-only tables (
glyph-pulse) keep a floor of 0.3 so they never vanish. - Dense IDE panels. Twenty running tool rows each want a spinner: only rows that lead their region animate (all are their own region, but list cap 8 applies in sidebars); the rest show
◌. - Non-truecolor terminals. No colour ramps: stalled uses the terminal's yellow/red palette index and the text label; brightness trails become two levels (bold / dim).
- Slow terminals / SSH. Repaint writes only the loader cells (cursor-addressed), never the whole line; with high latency (configurable) frame ms is floored at 120 ms (proposed).
- Very fast agent.
show_delay300 ms (loaders.md) hides the loader on quick turns. - Very slow agent. After 10 min in one phase, frame ms rises to the table's calm rate (×1.5, proposed); the elapsed timer remains the liveness cue.
- Copy / select. Loader glyphs are excluded from text selection and from copied transcript text.
- Screen readers in terminals. Terminal screen readers read cell changes; the
Terminalsurface can disable cycling (a11y_static_terminal) so only phase changes write to the screen.
Notes for AI
- Import
GlyphLoaderfromoxyn_dioxusand includeGLYPH_LOADER_CSSplus the token stylesheet once. - A GPUI version exists:
GlyphLoaderElinoxyn_gpui. - Props to set first:
state,now. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.