ltk/docs/architecture.md

ltk architecture

If you are new to the library, start with docs/onboarding.md first. This document assumes you already know how to run an example and what kind of application surface you are trying to build.

This document covers the patterns that the small examples/ files cannot show: how a real application is structured on top of the [App] trait, how multiple surfaces coordinate, how theming is consumed, how to build animations, and where the cost of a frame actually lives.

For copy-pasteable patterns the canonical references are the two downstream consumers in the Eydos workspace:

• crustace (crustace/src/) — the Eydos shell. Layer-shell background surface + 8 overlays, system polling, MPRIS, notifications, animated OSD.
• loginmanager (loginmanager/src/) — greeter. keyboard_exclusive, single overlay, focus management, async PAM via set_channel_sender.

The rest of this document explains why those repos look the way they do.

If you are coming from cargo doc, keep the public API split in mind:

• ltk::window — normal application windows
• ltk::shell — layer-shell and overlays
• ltk::runtime — advanced runtime hooks and runtime-free embedding

This document mostly lives in the overlap between ltk::shell and ltk::runtime. If you only want to build a plain app window, stay with docs/onboarding.md and the ltk::window surface first.

Mental model

ltk is Elm-shaped. The application is a value implementing [App]; ltk drives the loop and the application reacts.

Every frame: ltk calls view() and overlays(), lays out the returned tree(s), draws them, and dispatches input events back as Message values which are fed to update(). There are no retained widgets. Element<Msg> is rebuilt from scratch every frame from the application's own state.

This sounds expensive and is actually fine. The widget tree is plain enums, the layout pass is a single recursive walk that already has to happen anyway, and as of the WidgetHandlers snapshot work the input dispatch path no longer rebuilds the tree per event. The only thing the app must avoid in view() is I/O (reading files, scanning directories, walking icon caches) — keep those in poll_external or behind a RefCell cache.

In practice, that model is easiest to adopt in three steps:

1. Start with the ltk::window mental model: one app state, one view(), one update(), one normal window.
2. Add ltk::shell concepts only if you need layer-shell or overlays.
3. Reach for ltk::runtime hooks only when you need async wakeups, invalidation narrowing, or embedding outside ltk::run().

The trait surface, by purpose

App looks intimidating — most of it is opt-in. Group the methods by what you actually need:

Always implement

• type Message — your message enum.
• view(&self) -> Element<Msg> — main surface contents.
• update(&mut self, msg: Msg) — state transitions.

Implement when your app is multi-surface

• overlays(&self) -> Vec<OverlaySpec<Msg>> — see Surface composition below.

Implement when your app is a shell component, not a window

• shell_mode() → ShellMode::Layer( Layer::Background | Bottom | Top | Overlay ).
• layer_anchor(), layer_size(), exclusive_zone(), keyboard_exclusive() — the layer-shell knobs.
• background_color() → Color::rgba( 0, 0, 0, 0 ) for transparent surfaces (panels, OSDs).

Implement when external state matters

• set_channel_sender(sender) — saved once at startup; clone into background threads to push messages into the loop without polling.
• poll_external() -> Vec<Msg> — called after every Wayland event and every poll_interval() tick. Drain receivers here.
• poll_interval() — None (event-driven only) or Some( Duration ) (timer wakeups for clocks, expiry, etc.).

Implement when input gestures matter

• on_swipe_up, on_swipe_down, on_swipe_progress, on_swipe_down_progress (follow-the-finger).
• on_tap — taps that miss every widget.
• on_key / on_key_with_modifiers — global hotkeys.
• swipe_threshold, swipe_down_threshold — gesture sensitivity.

Implement for animations and focus

• is_animating() — return true while a tween is running; the loop redraws at ~60 Hz.
• take_focus_request() → Option<WidgetId> — pull-once focus retargeting.
• on_text_input_focused(active) — surface IME state.

The defaults for everything else are sensible enough that a minimal app overrides only the four methods in the first group.

Another way to read the trait is by API layer:

• ltk::window: view, update, plus the widgets/layouts you use to build the tree.
• ltk::shell: shell_mode, layer_anchor, layer_size, exclusive_zone, keyboard_exclusive, overlays.
• ltk::runtime: set_channel_sender, poll_external, poll_interval, invalidate_after, take_focus_request, is_animating, and core::UiSurface.

That is the intended order of adoption for third-party users.

Surface composition

The main surface is what view() paints. overlays() returns a Vec<OverlaySpec<Msg>> describing additional layer-shell surfaces that should exist this frame. The runtime diffs that list against the previous frame using [OverlayId]:

• Same id present last frame and this frame → keep the surface alive, only re-render its view.
• New id → create a new layer-shell surface.
• Id missing → destroy the surface.

This is why crustace declares stable const OVERLAY_LAUNCHER: OverlayId = OverlayId(1) etc. at the top of app.rs. Don't allocate ids dynamically — diffing relies on stability.

Each overlay carries its own view, anchor, size, layer, keyboard_exclusive, input_region, and on_dismiss. The Message type is shared with the main app: a button inside an overlay produces the same Msg that a button on the main surface would, and update() handles both. There is no per-overlay state machine — overlays are pure projections of App state.

on_dismiss is fired by three independent paths: a popup_done event from the compositor (xdg-popup mode); a pointer / touch press on the main surface that does not land on the trigger pointed at by anchor_widget_id while the overlay is mapped (covers compositors that route the button to the parent surface instead of breaking the popup grab); and Escape pressed while at least one xdg-popup overlay is open. The application only has to flip its is_open flag to false in update(); the runtime tolerates the message arriving more than once for the same open / close cycle.

Common patterns:

• Modal panel: layer: Overlay, anchor: ALL, keyboard_exclusive: false, on_dismiss: Some( CloseMsg ). Tap-outside dismisses; the panel itself centers via column().push(spacer()).push(panel).push(spacer()).
• Pass-through OSD: same as above but input_region: Some(Vec::new()) so pointer events fall through to whatever is below.
• Top bar / dock: layer: Top or Bottom, anchor: TOP/BOTTOM, fixed size, non-zero exclusive_zone so app windows reflow around it. Usually returned from view() (single-purpose shell), not from overlays().
• Greeter / lock screen: shell_mode: Layer(Overlay), keyboard_exclusive: true. Loginmanager is the reference.

Overlays do not nest. A "submenu inside the quick settings panel" is just a second overlay with a different id whose view() builds the submenu. Crustace uses this for the WiFi and Bluetooth pickers.

If your application does not need overlays or layer-shell, you can ignore this entire section and stay in the ltk::window subset.

Theming

ltk::theme exposes a process-wide active theme. Three layers:

1. Document — a [ThemeDocument] loaded from disk (/usr/share/ltk/themes/<id>/theme.json). Each document carries a light and dark [Mode] with a typed [SlotStore] (colors, paints, shadows, surfaces, text styles), wallpaper/lockscreen/launcher specs and a shared fonts block. When the default document cannot be located ltk falls back to an embedded B/W theme + embedded Sora Regular font, logs a stderr warning, and stamps every frame with a red banner pointing at the ltk-theme-default Debian package so the missing-theme signal is visible without the process aborting. ltk::is_fallback_active() exposes the state for apps that want to react programmatically.
2. Mode — [ThemeMode::Light] or Dark; flips which mode of the document is active.
3. Active state — ltk::active_document() / ltk::active_mode() return the current pair. Per-slot shorthands (ltk::theme_color, theme_paint, theme_shadows, theme_surface, theme_text_style, theme_palette, theme_window_controls, theme_wallpaper, theme_lockscreen) cover the common patterns.

Inside a widget tree, read the palette through the per-slot helper:

# fn _ex() {
let _label = ltk::text( "Hello" )
    .color( ltk::theme_palette().text_primary );
# }

To switch theme at runtime, dispatch a message that calls ltk::set_active_mode( ThemeMode::Dark ) from update() and let the next frame re-resolve. There is no manual invalidation step.

Loading a different document:

let doc = ltk::ThemeDocument::find( "default" )
    .expect( "default theme not installed (ltk-theme-default)" );
ltk::set_active_document( doc );

For dev iteration set LTK_THEMES_DIR=/path/to/ltk/themes so the lookup picks files in the working tree before the system path. The full search order is:

1. LTK_THEMES_DIR/<id>/ when the env var is set
2. $XDG_DATA_HOME/ltk/themes/<id>/ (defaults to ~/.local/share/ltk/themes/<id>/)
3. /usr/share/ltk/themes/<id>/

Wallpapers ship as a single landscape PNG per variant. ltk::WallpaperBundle::from_path_or_bytes( path, bundled_fallback ) handles the disk-or-builtin fallback, and bundle.for_size( sw, sh ) returns the right crop for landscape or portrait surfaces — no need to ship two PNGs.

For many third-party apps, theming is optional at first. It is reasonable to start with the default theme and come back to the runtime theme APIs later as part of the ltk::runtime layer.

Animations

The render loop is event-driven by default: it sleeps until input arrives, a poll_interval ticks, or set_channel_sender is woken from a thread. To run a tween, override is_animating():

# struct App { toast: Option<()>, nav_progress: f32 }
# impl App {
fn is_animating( &self ) -> bool
{
    self.toast.is_some()      // an OSD is fading
        || self.nav_progress < 1.0  // a screen is sliding
}
# }

While is_animating() returns true, ltk redraws at ~60 Hz. Do not mutate state in view(); instead read Instant::now() against a stored start time and compute the tween value:

# use std::time::Instant;
# use ltk::Element;
# const TOAST_DURATION: f32 = 3.0;
# #[ derive( Clone ) ] enum Msg {}
# struct App { toast_started: Option<Instant> }
# impl App {
fn view( &self ) -> Element<Msg>
{
    let progress = match self.toast_started
    {
        Some( t ) => ( t.elapsed().as_secs_f32() / TOAST_DURATION ).min( 1.0 ),
        None      => 0.0,
    };
    // … fade alpha = 1.0 - progress
#   ltk::text( "" ).into()
}
# }

The end-of-animation cleanup belongs in poll_external(): when progress >= 1.0 clear self.toast_started so is_animating() returns false and the loop sleeps again.

For follow-the-finger gestures use on_swipe_progress(progress) / on_swipe_down_progress(progress). Those fire continuously during the drag with a 0.0..=1.0 value and don't require is_animating — the gesture itself drives the redraw.

For a basic application window, defer this whole area until the rest of the UI is already working. Animation is part of the advanced runtime surface, not the core onboarding path.

Larger state patterns

A four-button demo can keep all state in one struct and one flat Msg enum. Anything bigger needs structure. Conventions used by crustace and loginmanager:

One module per screen / panel. Each module owns its sub-state struct and its sub-message enum, and exposes fn view(...) -> Element<AppMsg> and fn update(&mut self, msg: SubMsg) (or the parent inlines those calls). See crustace/src/homescreen.rs, launcher/, notifications.rs, powermenu.rs.

Wrap sub-messages in the top-level enum. enum AppMsg { Home(HomeMsg), Settings(SettingsMsg), Nav(Route), Tick }. update() matches the outer variant, then forwards to the right sub-module. This avoids one-giant-message-enum bloat once the app passes ~30 variants.

Ephemeral caches behind RefCell (single-threaded). view(&self) is &self; if you need a mutable icon cache, scaled-image cache, layout cache, etc., wrap it in RefCell<...> on the app struct and borrow_mut() inside view(). Crustace's IconCache does exactly this. Don't reach for Mutex — the event loop is single-threaded.

External state via channel + poll. Anything that blocks (D-Bus, files, network, IPC) lives on a background thread. At startup save the ChannelSender<Msg> from set_channel_sender, hand a clone to the worker, and have the worker push messages back. poll_external() is the place for non-blocking try_recv() against in-process receivers (e.g. mpsc/crossbeam channels) or for expiry checks like "is this notification past its TTL".

Stable widget ids only when you need to programmatically focus them. WidgetId is an opt-in tag on a widget that pairs with App::take_focus_request(). Don't decorate every widget; tag the one input you want to autofocus on screen entry.

Again, the simplest progression is:

1. one flat app state in ltk::window
2. sub-state and overlays once the app becomes shell-like
3. caches, channels, focus retargeting, and cross-surface invalidation only when scale requires them

Performance

The cheap things and the expensive things, in rough order:

• Cheap: building the Element<Msg> tree. It's plain enums and Vecs. crustace rebuilds the entire shell every frame and stays idle when nothing changes.
• Cheap: input dispatch. Per-leaf handler snapshots are captured during the layout pass; pointer/key events are O(N_focusable_leaves) lookups, not tree walks.
• Cheap: active_document() / theme_palette(). The first returns a clone of an Arc<ThemeDocument> from a RwLock-protected cell; the second projects the active mode's slot table onto the eight canonical palette fields.
• Avoid in view(): filesystem walks, image decoding, serde parsing, regex compilation. Cache the result on the app struct (behind RefCell if needed) and look it up.
• Avoid in view(): cloning large Vec<u8> image buffers. img_widget takes an Arc<Vec<u8>>; build the Arc once at load time and clone the Arc, not the bytes.
• Avoid is_animating() = true when nothing is moving. It pegs the loop at 60 Hz and burns battery on the mobile target.
• Lower poll_interval() is not free. Crustace polls every 30 s because the clock only shows HH:MM. If your UI shows seconds, Some(Duration::from_secs(1)) is fine; if it shows nothing time-sensitive, leave it None.
• Scroll viewports own a sub-canvas. They're slightly more expensive to draw than a plain column. Use them when you need clipping or actual scrolling, not as a wrapper.
• GPU vs software: the GLES path is selected automatically when EGL is available; both render the same pixels (see the recent commits for the alpha/SDF parity work). There is no API-level difference for the application.

When a redraw feels sluggish: add a one-line print at the top of view() and confirm it's not being called more often than expected. The single most common mistake is leaving is_animating() returning true after the animation finished.

Where to look in the consumer repos

Pattern	File
Multi-overlay coordination, overlay id constants	crustace/src/app.rs (overlays(), lines ~250–380)
Background poller + channel sender	crustace/src/app.rs (set_channel_sender, poll_external)
Sub-module per screen	crustace/src/{homescreen.rs, notifications.rs, powermenu.rs, launcher/}
Cached icon loading via RefCell	crustace/src/launcher/icon_cache.rs and use sites in app.rs
OSD overlay with auto-expiry	crustace/src/app.rs (show_osd, build_osd, OSD_TIMEOUT_SECS)
keyboard_exclusive + take_focus_request	loginmanager/src/main.rs
Theme on disk (slot-typed JSON)	ltk/themes/default/theme.json, ltk::ThemeDocument::find

For a self-contained example that exercises overlays, theme switching, and animation in one ~300-line file, see examples/mini_shell.rs.