The screen

Three tiers of screen

Legion supports three levels of display capability, called tiers. An app declares the minimum tier it needs, and Legion runs it on any device whose tier meets or exceeds that requirement.

Three-tier pyramidleg-display-tiers

A pyramid divided into three horizontal layers. Top (narrowest, dark blue): 'Tier 3 — Full'. Middle (medium, medium blue): 'Tier 2 — Standard'. Bottom (widest, light blue): 'Tier 1 — Minimal'. On the left of each layer, a small device icon: Tier 3 = smartphone, Tier 2 = Raspberry Pi, Tier 1 = microcontroller with small screen. Clean, modern pyramid diagram.

Tier 3 — The full experience

Devices: Smartphones, tablets, desktops, browsers

Rendering engine: A web view (like an invisible browser tab) built into the app. JavaScript is disabled in the web view — all logic runs in Legion's engine. The web view only renders HTML and CSS.

What it supports:

• Full HTML/CSS (including CSS Grid, flexbox, animations)
• Custom fonts
• Responsive layouts
• All interaction types (click, scroll, keyboard, touch)

This is what you'd expect from a modern app. Everything works.

Phone mockupleg-tier3

A modern smartphone (like iPhone or Pixel) shown front-facing. The screen shows a clean app interface — a chat or dashboard UI with rounded cards, icons, and a text input field at the bottom. The UI looks like a modern mobile app. Soft shadows, light background, blue accent color.

Tier 2 — The standard experience

Devices: Raspberry Pi, embedded Linux, TVs, low-power desktops

Rendering engine: litehtml, a lightweight C-based HTML renderer. It handles most modern HTML/CSS but without the heaviest features (no JavaScript, no animations).

What it supports:

• All Tier 1 features
• Tables, forms, more form controls
• Flexbox layouts
• Hover and focus effects (for mouse/keyboard input)
• CSS custom properties

This is enough for most useful apps. It's what you'd get from a browser in 2010, but optimized for low-power hardware.

Pi screen mockupleg-tier2

A small LCD screen (like a Raspberry Pi display, maybe 5-7 inches) showing a clean app interface. The UI is slightly simpler than a phone app — larger fonts, bolder outlines, fewer subtle effects. Still looks professional but clearly designed for a smaller, lower-resolution display. Think 'kiosk interface' or 'smart home dashboard on a small screen'.

Tier 1 — The minimal experience

Devices: Microcontrollers (ESP32), e-ink displays, embedded screens

Rendering engine: A custom, hand-written renderer. No external libraries. Tiny footprint (works in a few KB of RAM).

What it supports:

• Basic text (headings, paragraphs, lists)
• Simple buttons and text input
• Images (only inline, no network loading)
• Basic layout (blocks and inline elements)

What it doesn't support:

• No JavaScript
• No flexbox or grid
• No scrolling containers
• No animations

This is the “Hello World” of displays. Enough for status screens, simple menus, and text-based apps. Not enough for complex interfaces.

Microcontroller screenleg-tier1

A small monochrome or 2-color LCD screen (like an ESP32 dev board display, about 1.5 inches) showing simple text: 'Hello, Legion!' and a couple of button labels '(A) Start (B) Stop'. Minimal, utilitarian, retro-modern feel. Think 'e-ink reader or small IoT display'. Black and white or black and green color scheme.

How the app talks to the screen

The app produces HTML. Legion passes that HTML to the rendering engine appropriate for the device's tier. The renderer draws the UI. When the user interacts with the UI (taps a button, types text), the renderer sends events back to the app.

Two-way flow diagramleg-render-flow

A two-way vertical flow. Top box (blue): 'App produces HTML/CSS'. A downward arrow labeled 'Render'. A gray box in the middle: 'Renderer (Tier 1/2/3)'. An upward arrow labeled 'User events' (click, input, scroll). Bottom box (green): 'App receives events and updates state'. Clean, simple diagram.

The event model is straightforward. Events have a type (click, input, scroll, etc.), an element ID (which element was interacted with), and a value (the text that was typed, etc.). The app listens for events and responds:

legion.ui.onEvent((event) => {
    if (event.elementId === 'send-btn') {
        // User tapped the send button
        sendMessage(event.value);
    }
});

Asset loading — no external URLs

Legion apps can include images, fonts, and other assets. But they can't load them from the internet. Every asset must be:

1. Bundled with the app, or
2. Stored on a Legion node and referenced by its content hash

The syntax for referencing an asset looks like this:

<img src="legion-asset://sha256:a1b2c3d4..." alt="Logo">

Legion resolves this reference by looking up the content hash in its local cache and substituting the actual image data. The renderer never makes a network request — everything is already local.

Asset reference diagramleg-assets

A simple diagram showing an HTML img tag on the left pointing to a hash symbol (sha256:...) in the center, which points to a small image icon on the right. Small label above: 'No network requests — everything is local'. Clean, minimal. White background.

App handoff between devices

When you transfer an app from one device to another (phone to laptop, for example), Legion needs to preserve the app's state so the user experience is seamless.

There are two ways this can happen:

Lightweight handoff (preferred)

The app explicitly declares what state should be transferred:

legion.vm.onHandoffRequest(() => ({
    currentPage: state.page,
    scrollPosition: state.scrollY,
    selectedItem: state.selectedId
}));

This is efficient — only the essential state is transferred.

Full state transfer (fallback)

If the app doesn't implement lightweight handoff, Legion takes a snapshot of the entire virtual machine state (including all variables, timers, and internal state) and sends that to the destination device. This is more comprehensive but also more data.

In both cases, the app resumes at the exact same point. The user doesn't notice any interruption.

Rendering tiers in practice

When an app starts, Legion checks: “Does this device have a rendering tier high enough for this app?”

A higher-tier device can always run a lower-tier app — it just has more features available. Think of it like running a mobile app on a tablet: it works, just with more screen space.

Summary

The same app runs on all tiers — it just looks and behaves differently depending on what the device can do. This is Legion's version of “responsive design,” but at the platform level, not the CSS level.

What comes next

You've now seen how Legion looks on screen. The final page, Under the hood, ties everything together with a complete architecture map and explains how all the pieces fit together in the codebase.