Duolith docs

0012. Build a thin walking skeleton for web before Specification v0

  • Status: Accepted (provisional)
  • Date: 2026-11-14
  • Decided by: integrator (internal only)
  • Planning item: none; follows Mik's 14 Nov request to see a working example

Context

Mik asked to see a working example as early as possible. The roadmap puts Specification v0 (WP1) before the syntax, analyzer and web emitter packages. Building one thin path through every stage first shows the pipeline works end to end, exposes contract problems while they are cheap, and gives every later work package a place to plug in.

Decision

Build the smallest complete path from a .duo file to a running web page: page parser, element check against spec/language/elements.yaml, utilities from spec/styling/, a Screen IR, a web emitter and the state runtime in @duolith/client, driven by duolith build and duolith dev. Every format choice it makes is a proposal for WP1, not a settled part of the language:

  • A page is an optional --- script fence, then markup, then optional <style> blocks.
  • Script state is declared with state(...); reads and assignments of those names compile to .value access (Svelte-style), so pages never write .value themselves.
  • Expressions in markup are {...}; events are on:press and on:input; lists are <list each={...} as="name">.
  • Every container is a flex column stack; row turns one sideways. Element defaults never outrank a utility.
  • The web template is JSON mounted by the runtime; lists re-render rows when their items change (keyed recycling arrives with WP5).

Alternatives considered

OptionWhy not
Finish Specification v0 firstNothing runnable for weeks, and the contracts would be untested when the three tracks open
Generate the web output with AstroPulls a server-oriented build into a client-only framework (D16) and hides the Screen IR contract

Consequences

WP1 starts from working data files and a pipeline it can test against, and may change any of the choices above. The IR in crates/analyzer/src/ir.rs becomes the draft of spec/ir/. WP2, WP4, WP5 and WP7 replace their part of the skeleton rather than starting empty.