The execution ladder
The framework spends work at run time only where a screen needs it. Each file sits on a rung, from no script at all to code written in Rust, and the build decides the rung, not you. duolith build --report shows where each file landed and why.
The rungs
| Rung | What runs | Decided by |
|---|---|---|
| 0 | Nothing: the file is tables of constants | Every expression in the file is a constant (decision 0075) |
| 1 | The file's script, when the screen opens | Anything the screen only knows when it runs (decision 0076) |
| 2 | Functions compiled ahead of time to machine code | Closed until the native spike says so |
| 3 | Code written in Rust, in a module | You, by importing a Rust module (decision 0078) |
A file's own rung is 0 or 1; rungs 2 and 3 hold code a file calls.
Rung 0: tables
A page whose script holds only imports, types and constants (literals, arrays and objects of them, template strings, arithmetic, comparisons, toUpperCase, trim, join and the like) is folded: bound text becomes text, a <show> keeps the side its condition picks, a list of constant items is written out row by row (500 rows at most). On the web that module is data, and none of the script ships. A file is folded only when its tables come out smaller than its script.
Events and bind: always need rung 1, since handlers are functions. The report's summary, for examples/rust-module:
rung bytes saved bindings events file
1 4904 - 4 2 pages/index.duo /
0 2200 199 4 0 pages/about.duo /about
module maths (rung 3): 26123 bytes of WebAssembly, 7542 of loader, used by pages/index.duo
build-report.json gives each file's reason for its rung, such as "it imports ../modules/maths, which runs when the screen opens".
Written routes: HTML with no script
A web build goes one step further for a route whose page, layouts and every component they place fold onto rung 0: it writes the route's HTML into the route's file and loads no runtime, no route table and no module (decision 0162). The file is HTML and CSS. A component placed with constant props is folded with those props and written in place.
The report lists every route and how it is served:
routes:
/ written as HTML, no script
/count the app shell: pages/count.duo needs the runtime: it has state
In build-report.json that is routes, each with html (written or shell), script (none or runtime) and the reason a route is not written. What keeps a route from being written: state, an event or a bind: in the page, a layout or a placed component; a field or a form; an overlay; a radio group or a toolbar; an image that zooms; motion; a link or a button inside another; a route with a parameter. Links on a written route are plain links, and browsers that support it cross-fade between pages.
What is written is safe to serve as it is: text and attribute values are escaped, a link is written only to a path or an http, https, mailto, tel or sms address, there are no inline event handlers, and no state is put into the page. search-engines.md covers descriptions, headings and the sitemap.
Rung 1: source now, bytecode later
On the web rung 1 ships JavaScript source, which the browser compiles. On iOS and Android it will ship Lynx bytecode once the bytecode gate opens, and ships source until then. The gate (crates/runtime/src/ladder.rs) waits for the native spike to show bytecode starting faster than source on both phones; the build report carries its state (bytecode.isOpen, bytecode.waitingFor), so nobody mistakes one for the other.
Rung 2: closed
Compiling hot functions ahead of time waits for the same measurements, and promoting functions to it automatically is after version 1.
Rung 3: Rust
A function you write in a module in modules/<name>/ runs as WebAssembly on the web; Swift and Kotlin bindings come from UniFFI. The report lists each module with its sizes and the files that use it. See rust-modules.md.
The spike
spike/ holds the harness that answers the gate's question: one function timed as engine bytecode, compiled TypeScript and Rust. Its screens run in Lynx for Web here; the numbers that open the gate come from a mid-range Android phone and an iPhone, and only Mik declares go or no-go. spike/RESULTS.md records them.
Related
- production.md: the production adapters, on the web and on phones.
- native.md: how a native build is put together.