open-standards/joule-ui/docs/create.md

Create: describing an app, and the line language joule-ui takes in

A design note. The normative text is SPEC.md §11 (the line language) and the conformance pack in conformance/lang/. The WAI side is wai/wai-app/.

Create is a page where a person describes a WAI app ("a show for my channel, with chat and a live poll") and watches it build itself from WAI components while a model streams its answer. The room it builds is a real room on a room service. The person then exports it as a starter project.

1. The line language onto joule-ui's tree

A model writes OpenUI Lang (the open-source project's line-per-component language, MIT licensed; see NOTICE): one statement per line, name = Component(arg, ...), names usable before they are defined. joule-ui takes it in the way it takes in A2UI (joule-ui-a2ui): the language is a way to write a joule-ui widget tree against a host's registry, and what comes out is an ordinary Widget, checked by joule-ui's own validate.

The language	joule-ui
the library	the Registry, plus the name of its root widget
Component(a, b, c)	a Widget; the arguments map to props in the order the widget's schema lists (WidgetSchema::positional, new in core)
the prop named children in that order	Widget::children; a list of components
strings, numbers, booleans, null, lists, objects	Text, Number, Bool, (absent), List, Object
a reference to another statement	that statement's value (hoisting)
@Name(args) in a prop	PropValue::Action { id: "Name", payload }
$state, Query, Mutation, operators, ? :, member access, built-in functions, a sequence of actions	not carried: joule-ui puts no expression and no behaviour on the wire. Each is parsed (the grammar is parsed whole) and refused not-declarative, the smallest piece dropped

The crate is joule-ui-lang: a streaming parser, an ingest into widget trees validated against a registry, and a canonical writer back to the language. Every error names the line and the reason (unknown-component, missing-required, type-mismatch, disallowed-child, not-declarative, ...; the table is SPEC §11.8).

2. Streaming

The text arrives in chunks. After each chunk the parser gives a snapshot: the tree as far as it can be built, the errors so far, and the names still unresolved.

• Complete and pending. A statement is complete once its newline has arrived and the next non-blank character has too and is not ? (a line starting ? would continue a ternary). Complete statements never change. The last statement is pending: it is closed for the moment (an open string closed, open brackets closed in reverse order) and built, so a title shows letter by letter as it streams.
• What renders before the tree is whole. The tree starts at root. A reference to a statement not yet written is unresolved: in a list it is left out, in a prop it is absent. A widget whose required prop is absent only because something has not arrived is held back, silently, until it can render. So the first line, root = App([room], "Friday show"), renders an empty app at once, and each later line fills it in.
• How validation works on a stream. Every widget is validated against the registry as it is built, by joule-ui's validate; a widget that fails is dropped, and its error is reported once its statement is complete (a pending statement's problems may be gone by its next chunk). The snapshot's whole tree passes validate before it is handed to a renderer: no snapshot ever holds a widget the registry refuses. At the end of the stream the held-back cases become errors (missing-required, no-root), and the result equals parsing the whole text at once.

3. The WAI registry and the renderer

wai-app publishes a joule-ui registry of WAI widgets, each backed by the room client of joule-moq-web (the page that joins rooms, verifies every object against its receipt, watches together and keeps co-performance):

Widget	What it is
App(children, title)	the root
Room(children, title)	a live room: join with camera and microphone, or watch
WatchTogether(source, children, title)	a watch room: everyone watches one file in sync
Show(children, title, audience)	a room with co-performance: hosts on camera, an audience that votes
Player(title)	the room's video, laid out from its signed record
Chat(title)	the room's chat events, each verified; a participant sends
Poll(question, options, seconds)	a vote: the room's clock opens the window and signs the selection
Participants()	who is present, from the room's lifecycle
Receipts()	this page's sealed interaction log, verified, and the room's verified objects
EnergyMeter()	what each interaction cost, with how the figure was obtained
Text(text)	a paragraph

Each room kind accepts only the widgets its service keeps (a watch room carries co-watch statements alone, so it accepts no Chat and no Poll); joule-ui's AllowedChildren says so, and a line that puts a Poll in a WatchTogether is refused with its line and disallowed-child. An app holds one room.

The renderer (wai/wai-app/web/) reconciles each snapshot into the page by key (a statement's name), so a room already joined is never torn down by the next chunk. Every action a person fires (join, leave, send a chat, vote, play) goes through joule-ui-interaction in the page's WebAssembly build: authorized, metered (a page has no meter, so the figure is the estimator's, from the handler's wall time, and labelled so), and sealed into the page's hash-chained log under a key the page makes. Receipts shows the log and the page's own verify_chain of it. A browser handler is asynchronous, so the interaction crate gains a two-step form of its lifecycle (begin_interaction, then Pending::finish) with the same three phases; a denied action yields no Pending, so its handler cannot run.

4. Export

The page hands the person the program, app.oui, in the canonical form of the writer, and the command that makes it a project on their machine: wai create <dir> --from app.oui (the WAI toolchain's operation app.export). The project is an ordinary WAI project, the same kind wai create --template writes. Its project file, wai.json, is written by the one writer every WAI project file has, and names the program ("app": "app.oui") and the room wai dev runs for it ("dev": {"mode": "room" | "watch" | "show", ...}: a watch room's file, a show's audience inputs). Beside it are the program, the page that renders it with the same renderer and components, their runtime under vendor/ (each file with its SHA-256 in vendor.json), a README, an AGENTS.md for the next person or coding agent, and LICENSE: every project wai create writes is Apache-2.0, and says so. No key is in it.

It runs with wai dev (the relay, the room service and the page on one loopback origin, the keys made in .wai/, which is never committed and never served), and wai app check (app.check) checks it: app.oui against the registry, the room wai.json names against the app's own, and the runtime file by file. The app's files are made in Rust by one module (wai_app::export), and the project file by wai's, whoever asks (wai create --from, or the MCP server's app_export), so the project format changes in one place.

5. How a page talks to a model

Create spends nobody's money and holds no one's key on a server. Two ways in, and the page says which is in use:

• Your own model. The visitor names an endpoint that streams the common chat/completions server-sent-events format (a model server they run on their own machine, or a provider they hold a key for), a model name and a key. The page calls it from the browser. The key stays in the page's memory; it is never stored and never sent anywhere else.
• Your coding agent. wai mcp --toolset app is the WAI MCP server the visitor's own agent runs on their machine, with Create's toolset. Its tools give the agent the registry and the language (app_guide), check a program (app_check), stream a program into the visitor's open Create page through a bridge on 127.0.0.1 the page connects to with a pairing code (app_stream), and write the starter project into the agent's workspace (app_export, as wai create --from app.oui does).

A third mode replays a recorded stream, which is how the end-to-end test drives the page. A model hosted by the site is out of scope until the owner decides it.