Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 15 Packages Wiki Activity Actions 84
open-standards/joule-ui
History
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Transaction Science 608cd843e9 wai-app: Create's crate, a library with no binary, whose export wai create writes 
wai/wai-ui becomes wai/wai-app, the library `wai_app`, with no binary and no `cli`
feature: `wai`, built with its feature `app`, is its command line and its MCP
server. Its served files are named wai-app-* (the WebAssembly package wai_app),
the recordings wai-app-*.json.

- export.rs gives the files of a starter project for a program and the facts its
  project file holds (title, summary, `wai dev`'s mode for the app's room, a watch
  room's file, a show's audience); `wai create --from app.oui` writes them, the
  project file and the licence. The export no longer writes app.json, room.toml,
  relay.toml, package.json, check.mjs or serve.mjs: wai.json names the room, `wai
  dev` runs it and `wai app check` checks the project. Its README and AGENTS.md
  say so, and the README its licence.
- runtime.rs reads a Create runtime by its listing (create/wai-app-runtime.json),
  checking each file's SHA-256.
- bridge.rs keeps the bridge on 127.0.0.1 a coding agent streams a program into
  the page through, with a stream helper; the stdio server, its tools and the
  binary's test go (`wai mcp --toolset app` serves them).
- The page's Export hands over app.oui, the program in its canonical form, and the
  command that makes it a project; the ZIP writer and the page's export in
  WebAssembly go. The page names `wai mcp --toolset app` for the coding agent.
- joule-ui/docs/create.md §4 and §5: the export as `wai create --from app.oui`, and
  the agent's tools app_guide, app_check, app_stream and app_export.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-27 05:13:27 -04:00
..
conformance joule-ui: the line language (SPEC §11), a streaming ingest into validated widget trees 2026-10-27 04:46:19 -04:00
docs wai-app: Create's crate, a library with no binary, whose export wai create writes 2026-10-27 05:13:27 -04:00
joule-ui-rs joule-ui-interaction: a denial from begin_interaction is boxed (clippy result_large_err); wai/CHANGELOG: wai-ui and Create 2026-10-27 04:46:29 -04:00
LICENSE joule-ui: typed declarative protocol for agent-emitted user interfaces 2026-05-30 09:43:56 -04:00
NOTICE joule-ui: the line language (SPEC §11), a streaming ingest into validated widget trees 2026-10-27 04:46:19 -04:00
README.md joule-ui: the line language (SPEC §11), a streaming ingest into validated widget trees 2026-10-27 04:46:19 -04:00
SPEC.md joule-ui: the line language (SPEC §11), a streaming ingest into validated widget trees 2026-10-27 04:46:19 -04:00

README.md

joule-ui

A typed declarative protocol for agent-emitted user interfaces.

joule-ui is the sibling to JouleClaw for the moment when an agent's resolution has to become something a human can see and interact with. The agent emits a widget tree — (name, props, children), recursively — against a widget registry the host has published. The host renders. No React in the spec, no HTML over the wire, no agent holding the renderer.

The shape the field has converged on for this is declarative components against a registry: agents are far more reliable emitting structured data than emitting code, and renderers are far easier to harden when they own their own widgets. joule-ui pins that shape as a protocol; the renderer is product surface, owned by the consumer.

What ships in v1

  • joule-ui-rs/crates/joule-ui-core/ — the protocol types (Widget, PropValue, WidgetSchema, Registry) and the recursive validator. Pure Rust, no IO, JSON-serialisable.

  • joule-ui-rs/crates/joule-ui-interaction/ (v0.2) — the layer no other UI protocol carries: when a human or an agent fires an Action, the invocation is an accountable event. Every fire names the principal that made it — a did:key, the same whether a person or an agent (the protocol draws no distinction; both are traced). run_interaction authorizes it against a capability before it runs (a denied action's handler never executes), meters it in joules, charges its cost (a reading or an estimate, and which), and an InteractionLog seals it as the next link of a hash-chained receipt. The actor is bound into the signed core, so an interaction cannot be re-attributed without breaking the chain. A joule-ui session becomes a tamper-evident ledger of who fired it, what it computed, and what it cost — verifiable by anyone holding the host's key. The metering (Sandbox PowerMeter) and the capability (JCP grant) are recognized edges; the receipt, the chain, and the lifecycle are joule-ui's. See SPEC.md §5–§7 and examples/metered_surface.rs for the full loop.

  • joule-ui-rs/crates/joule-ui-lang/ (v0.3) — the line language: a model writes a surface as a short program, one widget a line (OpenUI Lang 1.0; see NOTICE), and joule-ui takes it in as it streams. After every chunk a snapshot holds the tree as far as it can be built, each widget validated against the registry, and every error with its line and reason; a canonical writer turns a tree back into the language. State, queries, expressions and sequences of actions are refused not-declarative: joule-ui carries no behaviour on the wire. See SPEC.md §11, the pack in conformance/lang/ with its independent verifier, and docs/create.md, the design of Create, the page that builds a WAI app as a model describes it.

The surface layer makes joule-ui a peer of the declarative-UI protocols (A2UI, MCP Apps). The interaction layer makes it the only one you can hand to an auditor: a UI whose every interaction is energy-accounted and sealed, by construction.

What is not here:

  • A renderer. The renderer is owned by the host (browser app, native shell, terminal UI). joule-ui validates the surface and seals the interaction; it does not paint pixels.
  • A transport. The validated spec and the interaction stream ride MCP, REST, SSE, gRPC, Web MoQ — any bytes-out protocol. Transport-agnostic.
  • A "model emits React" path. The agent emits a declarative tree against the registry; arbitrary code emission is out of scope.

Why a sibling, not inside JouleClaw

The spec layer is protocol — small, stable, conformant. The renderer registry is product surface — many of them, evolving fast. Splitting them protects the tools for use line: JouleClaw stays the runtime substrate; joule-ui is the UI protocol; consumers ship their own widgets.

Licence

Specification text and protocol document: CC-BY-4.0 (see LICENSE). Reference implementation in joule-ui-rs/: Apache-2.0 (see joule-ui-rs/LICENSE).