# wai-app

WAI's widgets for joule-ui, and **Create**: describe a WAI app, watch it build itself
from WAI widgets while a model writes it, try its room, and take it away as a project. A
library with no binary of its own: `wai`, built with its feature `app`, is its command line
and its MCP server. The design is in [`joule-ui/docs/create.md`](../../joule-ui/docs/create.md);
the line language a model writes the app in is joule-ui's (`joule-ui/SPEC.md` §11).

## The widgets

A joule-ui registry (`src/registry.rs`), each widget backed by the room client of
`joule-moq-web` (`web/components.js`):

| Widget | What it is | Holds |
|---|---|---|
| `App(children, title)` | the app | one room; `Text`, `Receipts`, `EnergyMeter` |
| `Room(children, title)` | a live room: join with camera and microphone, or watch | `Player`, `Chat`, and any room's widgets |
| `WatchTogether(source, children, title)` | a watch room: one file, watched in sync | any room's widgets (a watch room keeps the shared controls alone) |
| `Show(children, title, audience)` | a show: hosts on camera, an audience that votes | `Player`, `Chat`, `Poll`, and any room's widgets |
| `Player(title)` | the room's video, laid out from its signed record | |
| `Chat(title)` | the room's chat, each message a signed, verified event | |
| `Poll(question, options, seconds)` | a vote the show's lead opens and its clock closes and signs | |
| `Participants(title)` | who is present, from the room's lifecycle | |
| `Receipts(title)` | the page's sealed log of every action, verified | |
| `EnergyMeter(title)` | each action's energy, and how it was obtained | |
| `Text(text)` | a paragraph | |

Any room's widgets: `Participants`, `Receipts`, `EnergyMeter`, `Text`. An app holds one
room; a poll has 2 to 32 options; a show's audience is 1 to 255; a watch room's source is
a file within the app (`src/plan.rs`). A line that breaks a rule is refused with its line
and a reason code, and does not render.

## The pieces

- `src/guide.rs`: what a model is told before it writes an app, made from the registry
  (`wai app guide`, the tool `app_guide`).
- `src/lib.rs`: `check` and `Create`, a program as a snapshot the page renders, whole or
  as it streams, with the room the app needs (`wai app check`, the tool `app_check`).
- `src/export.rs`: the files of a starter project for a program, and the facts its project
  file holds: `app.oui`, `index.html`, `README.md`, `AGENTS.md`, `.gitignore`,
  `vendor.json`, `vendor/` (the runtime), and for a watch room `media/README.md`.
  `wai create <dir> --from app.oui` writes them, with `wai.json` and `LICENSE` from the
  writer every `wai create` project has. No key is ever in it: `wai dev` makes development
  keys in `.wai/` at run time.
- `src/runtime.rs`: the runtime an export carries, read by its listing
  (`create/wai-app-runtime.json`) and checked file by file.
- `src/bridge.rs`: the bridge on 127.0.0.1 that carries a program from a coding agent into
  the person's open Create page (`wai mcp --toolset app`, the tool `app_stream`).
- `src/web.rs` (feature `web`): the page's WebAssembly surface, with the interaction log
  every action on the page is sealed into (joule-ui-interaction).
- `web/`: the streaming renderer, the components, the room frame, the Create page and the
  exported app's page; `web/runtime.mjs` lays the runtime out as the site serves it.

## Run it

```
cargo test                                      # registry, plan, guide, export, runtime, bridge
node --test web/web.test.mjs                    # the renderer and the model streams
e2e/run.sh                                      # Create in a browser, with wai dev, wai create --from and wai app check
wai app guide                                   # what a model is told (wai built with --features app)
wai app check app.oui                           # a program's tree, errors and room
wai create my-app --from app.oui --runtime <dir> # a starter project; then wai app check and wai dev in it
wai mcp --toolset app                           # Create's tools, for a coding agent
```

## Licence

Apache-2.0, and every project `wai create` writes from an app is too.