1# llimphi
2
3> Native UI framework — 2D **and** 3D: HAL · raster · layout · text · theme · ui · 3D voxel engine — plus widgets and modules.
4
5`llimphi` is a sovereign, retained-mode UI framework with an Elm-style loop (`input → update → view → layout → raster → present`). Declarative pipeline over `vello` 0.9 + `wgpu` 29 + `taffy` 0.12 + `parley` 0.6, with `Dark/Light/Aurora/Sunset/Tawa` themes, AccessKit accessibility and a multi-platform HAL (Wayland · X11 · Win32 · Android · Wawa bare-metal). It powers a full Rust application suite; this repository is the framework extracted to stand on its own.
6
7<p align="center">
8  <img src="docs/showreel.gif" alt="Llimphi showreel — real widgets (switch, slider, progress, segmented control, buttons, radial) animating live, then reflowing across layouts" width="900">
9  <br>
10  <sub>real widgets in motion — rendered headless, frame-by-frame, fully deterministic</sub>
11</p>
12
13<p align="center">
14  <a href="docs/llimphi-tour.mp4"><img src="docs/llimphi-tour.jpg" alt="Frame from the 15-second Llimphi tour: a voxel island under a snow-capped Andean peak, a character celebrating while a hand writes llimphi in cursive" width="720"></a>
15  <br>
16  <sub><a href="docs/llimphi-tour.mp4">▶ 15-second tour</a> — a terminal prompt turns into a glass input, nine real widgets unfold, then a 3D sky, a 2.5D corridor and an endless voxel world under a snowy peak. Every frame is painted by llimphi.</sub>
17</p>
18
19<p align="center">
20  <img src="docs/counter.gif" alt="counter example — the full Elm loop in ~124 LOC" width="480">
21  <br>
22  <sub>…and the entire Elm loop in ~124 LOC — <code>cargo run -p llimphi-ui --example counter</code></sub>
23</p>
24
25## Not just 2D — a 3D voxel engine
26
27<p align="center">
28  <img src="docs/llimphi_voxel.gif" alt="Flying over an endless procedural voxel world — rendered by llimphi-3d" width="720">
29  <br>
30  <sub>flying over an endless voxel world — rendered headless by <code>llimphi-3d</code>, frame-by-frame</sub>
31</p>
32
33`llimphi-3d` is a **3D engine** on the same `wgpu`: it composes voxels (a GPU ray-march) and triangle meshes in one shared depth pass, with a keyframed cinema camera. It mounts into the ordinary 2D `View` tree through the GPU paint node (`set_viewport` + scissor), so a 3D viewport can live in a panel next to regular widgets — no second window, same Elm loop.
34
35`llimphi-voxel` adds the *content* layer on top: procedural world-gen (`WorldRecipe`), articulated characters (age + animation clips) and a scripted scene **director**. The GIF above is one such world. (A full voxel **world studio** — edit worlds, cast characters, direct filmed scenes, export to video — is built on these in the wider project.)
36
37**Usage manual:** [MANUAL.md](MANUAL.md) — full reference (Elm loop, `View<Msg>` DSL, the 79 widgets and 11 modules, GPU path, gotchas) for humans and AI. Design rationale and roadmap: [SDD.md](SDD.md).
38
39Philosophy: **widgets aren't designed against mockups; they're designed with what `vello` and `taffy` can do.**
40
41## Quick start
42
43```sh
44git clone https://git.tawasuyu.net/tawasuyu/llimphi.git
45cd llimphi
46cargo run -p llimphi-ui --example counter   # ~124 LOC: the full Elm loop on screen
47cargo run -p llimphi-gallery --release      # the widget gallery
48```
49
50## Install
51
52From git — this repository is the current tree (widgets are one crate each — pull only what you use):
53
54```toml
55[dependencies]
56llimphi-ui    = { git = "https://git.tawasuyu.net/tawasuyu/llimphi.git" }
57llimphi-theme = { git = "https://git.tawasuyu.net/tawasuyu/llimphi.git" }
58llimphi-widget-button = { git = "https://git.tawasuyu.net/tawasuyu/llimphi.git" }
59```
60
61crates.io holds an older 0.1 snapshot (June 2026, before the wgpu 29 / vello 0.9 move): `cargo add llimphi` gets the facade that re-exports `llimphi-ui`, `llimphi-theme` and `llimphi-3d`, but newer crates such as `llimphi-test` and `llimphi-anim` are not published there yet.
62
63## Beyond the 2D widget kit
64
65Pieces worth naming because they change what an app can be:
66
67- **Four paths to pixels, one compositor.** `vello` on GPU compute is the main road;
68  `llimphi-cpu` (`vello_cpu`) paints the bare-metal framebuffer; `llimphi-hybrid`
69  (`vello_hybrid`) is CPU+GPU with no compute shaders, for hardware that lacks it
70  (this is the one that runs on a phone's Mali); and `llimphi-wire-escena` serializes
71  a scene so a sandboxed guest can compose it and a host replay it. The same scene
72  tree goes through all of them and the output is diffed **per pixel** — wire vs
73  direct is bit-identical, hybrid vs CPU never differs by more than 1/255.
74- **Text.** `parley` shapes; `llimphi-glifos` rasterizes each glyph once into a
75  shelf-packed coverage atlas (4 subpixel positions per axis) so a line of text is
76  quads instead of outlines — 3.6–5× faster on the direct-GPU path.
77- **Testing.** `llimphi-test` is the headless, deterministic golden-image harness —
78  the reason a UI change can be certified as *text* (pixel-diff counts per threshold)
79  instead of by looking at a screenshot. Where two paths should paint the same thing,
80  the oracle is the other path, not a blessed image.
81- **Animation.** `llimphi-anim` is a Rive-style, clip-agnostic state machine;
82  `llimphi-lottie` and `llimphi-svg` are thin bridges to `velato` and `vello_svg`;
83  `llimphi-mesh` renders deformable meshes with bones and skinning.
84- **Surfaces.** `llimphi-layer` runs an `App` as a `wlr-layer-shell` surface (a bar
85  anchored to a screen edge) rather than a window. `llimphi-term-graphics` covers the
86  terminal graphics protocols.
87
88## Compatibility
89
90- **Linux/Wayland** — primary backend.
91- **Linux/X11** — via XWayland.
92- **macOS / Windows** — `winit` + `wgpu`.
93- **Android** — HAL via `android` crates (`hybrid` is the renderer that works on Mali).
94- **Wawa bare-metal** — alternative framebuffer HAL, over `llimphi-cpu`.
95
96Full crate index (framework · widgets · modules · android) in [MANUAL.md](MANUAL.md) §19.
97
98## Considerations
99
100- **Single API: declarative `View<Msg>`.** No imperative, no foreign vDOM.
101- **Same scene tree on Wayland and Wawa**: HAL abstracts the surface.
102- Widgets are **purely visual**; modules encapsulate state + behavior.
103
104## Read more
105
106- [A graphics engine from scratch, entirely in Rust](https://gioser.net/blog/llimphi-motor-grafico-de-cero/) (Spanish) — why llimphi exists, the four paths to pixels and what is still missing.
107
108## License
109
110Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.