Duolith docs

0075. Rung 0: a file whose expressions are all constants is built as tables

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP13 (execution ladder), open decision D22

Context

The execution ladder (glossary: rung, 0 to 3) is how the framework spends runtime work only where a screen needs it. D22 asks for "rung 0 tables for static screens and bindings in version 1". Before this decision every page, layout and component became a module with a setup function that ran the file's script and returned one function per markup expression, even for a page that only shows text. Both emitters need the same answer to "is this file static?", and they share only the Screen IR.

Decision

  • The rung is decided beside the Screen IR, in the analyzer (crates/analyzer/src/ladder/): ladder(&ScreenIr) gives the rung, the report's facts and, on rung 0, the file folded onto tables as ordinary Screen IR, from one fold (ladder_facts and fold_to_tables give one half each). The web emitter uses them. The native emitter does not yet: the functions are there for it, beside the IR it already reads, but it builds every file as it did before. Nothing in the IR's shape changed (its types gained Clone).
  • A file is on rung 0 when every expression in it is a constant. Its script may hold only imports of components and the kit (and of @duolith/client, unused), types, and const/let declarations whose values are constants. A constant is worked out by a small evaluator that knows a pure part of JavaScript: literals, arrays and objects of them, template literals, arithmetic, comparison, logic, ?:, member access, .length, and toUpperCase, toLowerCase, trim and join. Numbers that JavaScript would write with an exponent, NaN, Infinity, == and identity comparison of lists are not constants. Anything else keeps the file on rung 1, and the report says which name or expression did (count is only known when the screen runs).
  • Folding onto rung 0: bound text becomes text; a <show> keeps the side its constant condition picks; a list of constant items is written out row by row (at most 500 rows across the whole file, with each copy of a list inside a list counted, past which the file stays on rung 1 with a warning); a class: whose condition holds stays with true, one that fails goes. Bound attributes and component props stay bindings, to a table of constants, so a property is still set the way the runtime sets it (checked, href and aria-* have their own rules).
  • On the web a rung 0 module is data: the components it places, imported, a table of constants, and its template with the fields only a script fills in (empty bindings, events, twoWay, classToggles, attributes, and repeat) left out. The runtime reads a missing field as empty. Its setup function only hands the table to the runtime, building the table's values afresh each time, so a list one placement changes is never what the next visit sees; none of the page's script ships.
  • Rung 0 only where it is smaller. Both modules are compiled; when the table module comes out larger than the rung 1 module (rows written out can repeat a large template), the file stays on rung 1 and the report says by how many bytes (its tables would be <n> bytes larger than its script). Saved bytes are never negative.
  • Events and bind: always need rung 1: their handlers are functions.

Measurements

From pnpm bench over every example (2026-11-14): 11 of 234 files are on rung 0 (5 of the 6 styling pages, the kit and media galleries' index pages, the about and library pages; none of the gallery's 64, the effects example's 27 or the production example's 15, which all run scripts), and their modules are 30,852 bytes smaller than on rung 1 (3.0 % of all 1,016,535 module bytes; the styling example's reference pages are 28,743 of it). The saving is the template's empty fields, not script: on the web a static page's rung 1 module was already almost only its template. A list written out row by row can cost bytes: examples/rust-module's about page is 535 bytes bigger written out than as a list before the template was compacted, and 199 bytes smaller after. The rung 0 pages render the same DOM as on rung 1 (checked page by page in Chromium; only a list's empty range markers differ).

Alternatives considered

OptionWhy not
Decide the rung in each emitterThe two targets could disagree about the same file
A new rung field in the Screen IRChanges the IR contract for something both emitters can compute from it
Evaluate constants with a JavaScript engine at build timeA second engine in the compiler, and it would accept code (dates, randomness) whose value differs at runtime
Fold attribute bindings into fixed attributes tooThe runtime sets some properties differently from attributes (disabled={false}, checked); keeping them as constant bindings keeps one behaviour
Keep rung 0 even when its tables are bigger in bytesA rung 0 file runs no script and creates no reactions, but a nested list written out grew one page's module to 38 MB in review; a size check is simpler than a better cap
Cap each list at 500 rows on its ownA list inside a list multiplies: 500 rows of 500 rows passed every per-list cap

Consequences

  • duolith build --report shows each file's rung and, on rung 1, why (decision 0079).
  • Adding a function to the evaluator is a compiler change, tested against how JavaScript answers.
  • The native emitter can build rung 0 files as Lynx element tables with no script thread work, once it calls ladder; until then native builds every file as before.