Duolith docs

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

RungWhat runsDecided by
0Nothing: the file is tables of constantsEvery expression in the file is a constant (decision 0075)
1The file's script, when the screen opensAnything the screen only knows when it runs (decision 0076)
2Functions compiled ahead of time to machine codeClosed until the native spike says so
3Code written in Rust, in a moduleYou, 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.

  • production.md: the production adapters, on the web and on phones.
  • native.md: how a native build is put together.