Duolith docs

0162. A web build writes each page's HTML, and ships script only where a page runs

  • Status: Accepted
  • Date: 2026-11-18
  • Decided by: Mik: chose "add prerendering first" and asked for a compiler that can tell what can be static HTML, then chose "our own HTML and islands" over Astro output, and approved the record on 18 Nov 2026 ("Approved for prerendering")
  • Planning item: none (the public site, and decision 0090's "revisit")

Context

A web build today is one app shell and a route table. Every route's HTML file holds an empty <div id="duolith-root">, and the browser downloads the runtime (62 modules, 96 KB gzip for examples/minimal) before any text shows. Three things follow:

  • Search engines and link previews see nothing. A crawler that does not run script reads an empty page, and one that does waits for the runtime.
  • A page that does nothing still pays for everything. The execution ladder (decision 0075) already proves, in the compiler, when a file is constants only: rung 0, "nothing runs". On the web that file is still a module of tables that the whole runtime is downloaded to mount.
  • The public site cannot be built with the framework (decision 0090), which is the first thing a visitor would check.

Mik's direction (18 Nov 2026): prerender first, then build the site on it; the compiler should tell what can be static HTML; work the state patterns in, as light and fast as possible; and nothing here may open a security hole in the compiled code.

What the compiler already knows makes this smaller than it sounds. A rung 0 file is folded at build time: bound text is text, a <show> keeps one side, a constant list is written out row by row. The web template the emitter builds from it is already HTML in all but spelling (tags, classes, attributes, text). And a component with load= is already an island with its own module (decision 0057).

Decision

A web build writes the HTML of each route that has no parameters into that route's file, and decides per route, from the ladder, how much script the route needs. Nothing changes in how pages are written, and nothing changes on iOS and Android.

  1. Three kinds of route, decided by the build. duolith build --report names each route's kind and the reason, as it does for rungs. | Kind | When | What the browser gets | | --- | --- | --- | | Written | The page, its layouts and every component they place fold onto rung 0 | HTML and CSS. No runtime, no route table, no module. | | Islands | The page and its layouts fold onto rung 0, and at least one component they place needs rung 1 | The written HTML, and a small loader that builds only those components, each when its load= says (at once when it has none) | | App | The page or a layout needs rung 1 | The written HTML of its first screen, and the parts of the runtime its patterns use, which take the screen over when they start |
  1. Rung 0 files are written by the compiler alone. The emitter turns the folded web template into HTML text in Rust, so a written route needs no Node, no browser and no second renderer: the same template the runtime would mount is what is written. A component placed with constant props is folded with those props and written in place, with the page's children at its slot. A component that does not fold with them (it has state, an event, a bind: or a <boundary>) is what makes the route an islands route.
  1. Rung 1 files are written from their first values, by reading their state as patterns. The compiler already reads state(...), derived(...) and the events as patterns. state(0) starts as a constant, so the first screen folds the way a rung 0 file folds: state holds its first value, a derived value is worked out from those, state that loads shows its skeleton, and a list of state shows its first rows. Nothing runs at build time: no Node, no browser. A first value that is not a constant (it reads the device, the clock or the network) leaves that part unwritten, the build report says which, and the runtime fills it in. If no file of the route can be written, the route's file is the shell it is today. The script a route ships is what its patterns use, and no more. The runtime is modules; the build knows which patterns each file uses (state, events, lists, shows, overlays, the router, the data layer), so a route's file loads only the modules those need, and attaches them to the HTML already there. A page with state and a press handler loads the state core and the event wiring, not the router or the overlays. What may never be written, whatever the pattern (each is a test):
    • Text and attribute values are escaped by the writer; there is no way to write markup from a value.
    • A link's address is written only if the runtime's own check allows it (a path, or http, https, mailto, tel, sms), so no javascript: or data: address reaches a file.
    • No inline event handler (onclick=), no eval, no innerHTML. Handlers are attached by a module from the app's own origin, so the strict Content-Security-Policy (decision 0150) is unchanged, and a written route's policy lists fewer scripts, not more.
    • No state is serialized into the page for the script to read back. First values live in the module that already holds them. Only build-time constants are written into HTML; nothing read from the network, from storage or from the address ever is. This is the rule for every file a build writes. A server that renders a route for one request is a separate proposal (decision 0163), and what it may hand to the browser is decided there.
  1. Taking over. When the runtime starts on an app route it builds the screen as it does today and replaces the written HTML with it in one step, so the page never shows two states. The written HTML and the built screen must be the same text; a browser test compares them for every example. Adopting the written nodes instead of rebuilding them (hydration proper) waits until a measurement says the replacement costs something.
  1. Links. A written or islands route has no router, so its links are plain links and the browser loads the next route's file. Those routes carry @view-transition { navigation: auto; }, so browsers that support it cross-fade between pages without script. Inside an app route the router navigates as today, and it still reaches a written route in place, because every page keeps its module.
  1. What the page says about itself. For search engines and link previews:
    • <screen description="..."> is the page's description (<meta name="description">, and the description a link preview shows). It is text or a constant, like title on a written route.
    • <text role="heading"> takes level="1" to level="6" and is written as <h1> to <h6> (without a level it stays a level 2 heading, as assistive technology reads it today).
    • duolith.yaml gains web: url: (the address the site is served from) and web: image: (the picture a link preview shows). With a url, every route file carries its canonical address and Open Graph tags, and the build writes sitemap.xml and robots.txt. Without one, none of these are written, and the build says so once.
  1. Astro output is not written (Mik, 18 Nov 2026: "our own HTML and islands"). See the alternatives.
  1. The docs stay generated (decision 0090), because the guides are markdown. The public site's own pages (home, the story) become a Duolith app, built by duolith build, and the docs generator writes its pages beside it in the same folder. The home page is then a written route, and its weight is the number the site quotes.

Alternatives considered

OptionWhy not
Prerender in a headless browser at build timeExact, but a build would need Chromium (hundreds of megabytes) and seconds per route. The compiler already holds the answer for rung 0 files.
Prerender by running each page's script in NodeExact for any script, but it runs app code at build time (a script that touches localStorage throws there), needs a second renderer or a DOM library, and makes builds slower. Reading first values as patterns covers what a first screen shows, in the compiler.
Serialize state into the page for the script to pick upThe usual way to resume without re-running setup, and the usual way prerendered pages get script injection: a value that holds </script> or is built from the address ends up in markup. First values stay in the module.
Emit an Astro project (.astro pages with islands)Astro would need a renderer for our components to hydrate an island, so our runtime ships either way and Astro adds a second build, a second dev server and its own router beside ours. Its static HTML and islands are what items 1 to 5 give us directly. It would also tie the web target to another project's release cycle and name.
An Astro integration (Duolith components inside an Astro site)It would reuse the written HTML and the island loader, but it is a second product to keep working against Astro's releases. Not planned; Mik chose our own output alone.
Hydrate by adopting the written nodesNeeds a second pass over every part of the runtime that builds nodes (lists, shows, overlays, images). Replacing in one step gives the same pixels; revisit with a measurement.
Let the author mark pages staticThe compiler can prove it, and a mark can be wrong. The report says why a route is not written, which is the author's handle.

Consequences

  • A page with no state costs what its HTML and styles cost. The report's kind column, and the reason beside it, tell an author what one event handler did to a route.
  • A written route's first paint needs no script, so the strict Content-Security-Policy (decision 0150) gets shorter on those routes: no module, no start script.
  • The rule "the written HTML equals the built screen" is a new invariant with its own browser test. Anything the runtime does to a node while building it (an image's fade, a link's address check) must be done by the writer too, or must wait for the takeover.
  • Kit parts that hold state or events make a route an islands route, not a written one. Folding more of the kit with constant props is worth doing part by part.
  • The build must know, per file, which runtime modules its patterns need. That map is new, has to be exact (a missing module is a broken page), and is checked by loading every example's routes in a browser test.
  • spec/language/elements.yaml (description, level), spec/schemas/project.schema.json (web:) and the build report's schema change, with their reference pages and conformance fixtures.
  • Decision 0090's reasons shrink to one: the docs are markdown. Its "build the site as a Duolith app" row is answered here for the pages that are screens.