7cbbc19f0c
The skill's text is in the binary and in wai/wai-app/templates/SKILL.md, so it works offline and matches the installed version; each of the nine templates and Create's export holds it with a section of its own after the block. A rerun replaces only the block: a marker is a line of its own, markers that make no one block leave the file alone, and a file keeps its line endings. Co-Authored-By: Claude Opus 5.5 <[email protected]>
76 lines
4.8 KiB
Markdown
76 lines
4.8 KiB
Markdown
# 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`). The registry is the one source of the widgets: the
|
|
guide, and the two files of `widgets/`, are written from it.
|
|
|
|
| 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`).
|
|
- `widgets/`: the registry as files for tools that read widgets from a file:
|
|
`catalogue.json`, a JSON Schema of the widgets as a tree of nodes, and `library.json`, the
|
|
library a program in the line language is checked against. `tests/exports.rs` holds them to
|
|
the registry, and holds the catalogue to joule-ui's reading of those nodes; a widget added to
|
|
the registry fails there until `WAI_APP_BLESS=1 cargo test --test exports the_committed_files`
|
|
writes them again.
|
|
- `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`, the skill agents load
|
|
(`.agents/skills/wai/SKILL.md`, from `templates/SKILL.md`, the text `wai setup-agent` writes),
|
|
`.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.
|